@velastack/cms 0.1.0

package/dist/srv/api-adapter.js

@@ -0,0 +1,178 @@
+import { building } from '$app/environment';
+import { buildConfig } from 'virtual:vela-cms/build-config';
+/**
+ * The Vite plugin generates `virtual:vela-cms/build-config` with the
+ * project's resolved `{ uploadsBase, mediaPrefix }` (or `null` when the
+ * customer hasn't passed `cms({ endpoint })`). Inlining the value via a
+ * virtual module is the only way it survives into SvelteKit's prerender
+ * worker thread, which doesn't share `globalThis` with the plugin process.
+ */
+const getBuildMediaConfig = () => {
+    if (!building)
+        return null;
+    return buildConfig.media;
+};
+const RELATIVE_UPLOADS_RE = /^\/uploads\/([^/?#]+)$/;
+/**
+ * Deep-clone `value` and replace every `/uploads/<file>` (relative) and
+ * `<uploadsBase>/<file>` (absolute) string with `<mediaPrefix>/<file>`. Pure;
+ * cycle-safe via a WeakMap. Mirrors the helper in `plugin/src/media.ts` —
+ * deliberately duplicated to keep the runtime adapter free of plugin imports.
+ */
+const rewriteMediaUrls = (value, uploadsBase, mediaPrefix) => {
+    const seen = new WeakMap();
+    const prefix = `${uploadsBase}/`;
+    const normalizedPrefix = mediaPrefix.replace(/\/$/, '');
+    const walk = (v) => {
+        if (typeof v === 'string') {
+            const m = RELATIVE_UPLOADS_RE.exec(v);
+            if (m)
+                return `${normalizedPrefix}/${m[1]}`;
+            if (v.startsWith(prefix)) {
+                const rest = v.slice(prefix.length).split(/[?#]/)[0];
+                if (rest && !rest.includes('/'))
+                    return `${normalizedPrefix}/${rest}`;
+            }
+            return v;
+        }
+        if (!v || typeof v !== 'object')
+            return v;
+        const cached = seen.get(v);
+        if (cached !== undefined)
+            return cached;
+        if (Array.isArray(v)) {
+            const arr = [];
+            seen.set(v, arr);
+            for (const x of v)
+                arr.push(walk(x));
+            return arr;
+        }
+        const obj = {};
+        seen.set(v, obj);
+        for (const k of Object.keys(v)) {
+            obj[k] = walk(v[k]);
+        }
+        return obj;
+    };
+    return walk(value);
+};
+/**
+ * HTTP-backed adapter that talks to a remote @velastack/cms backend.
+ *
+ * Mirrors the in-memory mock's wire shape (one GET `/docs` per scope query;
+ * GET `/pages` for entry enumeration) so the same backend powers both the
+ * in-process mock and this adapter while the migration is in flight. Forwards
+ * `previewKey` as `?preview=…` so the backend overlays pending release edits
+ * when present. Uses the request-scoped `context.fetch` so SvelteKit can
+ * forward cookies during SSR.
+ */
+export const apiAdapter = (options) => {
+    const endpoint = options.endpoint.replace(/\/$/, '');
+    return {
+        endpoint,
+        async fetchDocs(queries, context) {
+            const out = {};
+            const mediaConfig = getBuildMediaConfig();
+            const extraSuffix = context.versionKey
+                ? `&version=${encodeURIComponent(context.versionKey)}`
+                : context.previewKey
+                    ? `&preview=${encodeURIComponent(context.previewKey)}`
+                    : '';
+            await Promise.all(queries.map(async (q) => {
+                const qs = new URLSearchParams({
+                    kind: q.kind,
+                    routeId: q.routeId,
+                    params: JSON.stringify(q.params),
+                    locale: q.locale
+                }).toString();
+                const res = await context.fetch(`${endpoint}/docs?${qs}${extraSuffix}`, {
+                    credentials: 'include'
+                });
+                if (res.status === 404)
+                    return;
+                if (!res.ok) {
+                    throw new Error(`apiAdapter.fetchDocs ${q.scopeId}: ${res.status}`);
+                }
+                const body = (await res.json());
+                if ('kind' in body) {
+                    out[q.scopeId] = body;
+                }
+                else {
+                    const contents = mediaConfig
+                        ? rewriteMediaUrls(body.contents, mediaConfig.uploadsBase, mediaConfig.mediaPrefix)
+                        : body.contents;
+                    out[q.scopeId] = { contents };
+                }
+            }));
+            return out;
+        },
+        async fetchSite(context) {
+            const qs = new URLSearchParams();
+            if (context.versionKey)
+                qs.set('version', context.versionKey);
+            else if (context.previewKey)
+                qs.set('preview', context.previewKey);
+            const suffix = qs.toString() ? `?${qs}` : '';
+            const res = await context.fetch(`${endpoint}/site${suffix}`, {
+                credentials: 'include'
+            });
+            if (res.status === 404)
+                return {};
+            if (!res.ok)
+                throw new Error(`apiAdapter.fetchSite: ${res.status}`);
+            const body = (await res.json());
+            const mediaConfig = getBuildMediaConfig();
+            const contents = mediaConfig
+                ? rewriteMediaUrls(body.contents, mediaConfig.uploadsBase, mediaConfig.mediaPrefix)
+                : body.contents;
+            return contents ?? {};
+        },
+        async fetchEntries(routeId, context) {
+            // Without `previewKey`: `/pages` is read-public; the backend returns
+            // published entries only when no `cms_session` cookie is present.
+            // For prerender we don't pass a cookie — we get published-only by
+            // construction. We still filter `isDraft` / `isDeletePending` /
+            // `gone` as a defensive belt-and-suspenders. Tombstoned entries
+            // with `redirectTo` are kept so prerender visits the URL and
+            // SvelteKit emits the redirect file.
+            //
+            // With `previewKey`: forward as `?preview=…` so the backend overlays
+            // the matching open release, and skip the filter so the editor sees
+            // staged additions/deletions.
+            //
+            // With `versionKey`: forward as `?version=…`; the backend returns
+            // the entry list as it was at that release's publish time. No drafts,
+            // no pending deletes — past releases are immutable.
+            const qs = new URLSearchParams({ locale: context.locale });
+            if (context.versionKey)
+                qs.set('version', context.versionKey);
+            else if (context.previewKey)
+                qs.set('preview', context.previewKey);
+            const res = await context.fetch(`${endpoint}/pages?${qs}`, {
+                credentials: 'include'
+            });
+            if (!res.ok)
+                throw new Error(`apiAdapter.fetchEntries: ${res.status}`);
+            const body = (await res.json());
+            const route = body.routes.find((r) => r.routeId === routeId);
+            if (!route)
+                return [];
+            const entries = context.versionKey || context.previewKey
+                ? route.entries
+                : route.entries.filter((e) => !e.isDraft && !e.isDeletePending && !e.gone);
+            const mediaConfig = getBuildMediaConfig();
+            return entries.map((e) => {
+                const metadata = e.metadata ?? {};
+                const rewritten = mediaConfig
+                    ? rewriteMediaUrls(metadata, mediaConfig.uploadsBase, mediaConfig.mediaPrefix)
+                    : metadata;
+                return {
+                    params: e.params,
+                    metadata: rewritten,
+                    ...(e.redirectTo ? { redirectTo: e.redirectTo } : {}),
+                    ...(e.gone ? { gone: true } : {})
+                };
+            });
+        }
+    };
+};

package/dist/srv/cms.d.ts

@@ -0,0 +1,62 @@
+import type { ServerLoadEvent } from '@sveltejs/kit';
+import type { RouteId, RouteParams } from '$app/types';
+import { type LoadCmsResult } from './load-cms.js';
+import type { CmsAdapter, CmsEntry, SiteSchema } from './types.js';
+export type CreateCmsOptions = {
+    /** Adapter that talks to the backing store. */
+    adapter: CmsAdapter;
+    /** BCP-47 supported locales, e.g. `'en'` or `'es-MX'`. */
+    locales: string[];
+    /**
+     * Project-wide site settings schema. Top-level keys become groups in the
+     * Site Settings panel; each group's `fields` keys become path segments in
+     * the stored tree (`branding.name`, `social.twitter`). Omit the option for
+     * projects that don't expose any editable site settings — the panel won't
+     * render any sections and the data layer keeps an empty tree.
+     */
+    site?: SiteSchema;
+};
+export type Cms = {
+    /**
+     * Resolve the CMS payload for the current SvelteKit request. Mirrors
+     * {@link loadCms} but with the adapter and locale already bound.
+     */
+    load: (event: ServerLoadEvent, { locale }: {
+        locale: string;
+    }) => Promise<LoadCmsResult>;
+    /**
+     * Enumerate every publishable entry the adapter has at one route.
+     * Resolves to `{ params, metadata }[]` — `params` for SvelteKit's
+     * prerender `entries()` export, `metadata` (lifted from each doc's
+     * reserved `_metadata` field) for index/listing pages that need a title
+     * or description per entry.
+     *
+     * Generic in the route id: pass a literal route (e.g.
+     * `'/(marketing)/rooms/[slug]' satisfies RouteId`) and `params` is typed
+     * as that route's `RouteParams` (e.g. `{ slug: string }`). When called
+     * with no `routeId`, the @velastack/cms Vite plugin substitutes the importing
+     * `+page.{ts,server.ts}`'s route id at build time; the static type then
+     * widens to the union of all routes, so prefer passing the route id
+     * explicitly when you need typed `params`.
+     */
+    generateEntries: {
+        (): Promise<CmsEntry<RouteParams<RouteId>>[]>;
+        <R extends RouteId>(routeId: R): Promise<CmsEntry<RouteParams<R>>[]>;
+    };
+};
+/**
+ * Bind a {@link CmsAdapter} + locale into a small object of helpers used by
+ * SvelteKit route files. The returned `load` and `generateEntries` close
+ * over the adapter, so call sites never re-pass it.
+ *
+ * Typical usage:
+ *
+ * ```ts
+ * // $lib/cms.ts
+ * import { createCms, mockAdapter } from '@velastack/cms/server';
+ * export const { load: loadCms, generateEntries } = createCms({
+ *   adapter: mockAdapter({ layoutDocs, pageDocs }),
+ * });
+ * ```
+ */
+export declare const createCms: (options: CreateCmsOptions) => Cms;

package/dist/srv/cms.js

@@ -0,0 +1,35 @@
+import { loadCms } from './load-cms.js';
+/**
+ * Bind a {@link CmsAdapter} + locale into a small object of helpers used by
+ * SvelteKit route files. The returned `load` and `generateEntries` close
+ * over the adapter, so call sites never re-pass it.
+ *
+ * Typical usage:
+ *
+ * ```ts
+ * // $lib/cms.ts
+ * import { createCms, mockAdapter } from '@velastack/cms/server';
+ * export const { load: loadCms, generateEntries } = createCms({
+ *   adapter: mockAdapter({ layoutDocs, pageDocs }),
+ * });
+ * ```
+ */
+export const createCms = (options) => {
+    const { adapter, locales, site } = options;
+    const defaultLocale = locales[0];
+    const siteSchema = site ?? {};
+    return {
+        load: (event, { locale }) => loadCms(event, { adapter, locale, locales, siteSchema }),
+        generateEntries: (async (routeId) => {
+            if (!routeId) {
+                throw new Error('generateEntries: routeId not injected. Did the @velastack/cms Vite plugin run?');
+            }
+            const entries = await adapter.fetchEntries(routeId, {
+                fetch,
+                locale: defaultLocale,
+                locales
+            });
+            return entries;
+        })
+    };
+};

package/dist/srv/index.d.ts

@@ -0,0 +1,5 @@
+export { loadCms, type LoadCmsOptions, type LoadCmsResult } from './load-cms.ts';
+export { createCms, type CreateCmsOptions, type Cms } from './cms.ts';
+export { mockAdapter, type MockAdapterOptions, type PageEntry, type ReleaseItemSnapshot, type ReleaseSnapshot } from './mock-adapter.ts';
+export { apiAdapter, type ApiAdapterOptions } from './api-adapter.ts';
+export type { CmsAdapter, CmsAdapterContext, CmsAdapterDoc, CmsAdapterResolution, CmsAdapterTombstone, CmsEntry, CmsScopeQuery } from './types.ts';

package/dist/srv/index.js

@@ -0,0 +1,4 @@
+export { loadCms } from "./load-cms.js";
+export { createCms } from "./cms.js";
+export { mockAdapter } from "./mock-adapter.js";
+export { apiAdapter } from "./api-adapter.js";

package/dist/srv/load-cms.d.ts

@@ -0,0 +1,105 @@
+import type { ServerLoadEvent } from '@sveltejs/kit';
+import type { CmsManifest, CmsPayload, SiteSchema } from '../components/cms/scope.ts';
+import type { CmsAdapter } from './types.ts';
+export type LoadCmsOptions = {
+    /** BCP-47 locale for the request, e.g. `'en'` or `'es-MX'`. */
+    locale: string;
+    /**
+     * BCP-47 supported locales. First entry is the default locale used for
+     * read-time fallback when a value is missing in the requested `locale`.
+     */
+    locales: string[];
+    /** Adapter that talks to the backing store. See {@link CmsAdapter}. */
+    adapter: CmsAdapter;
+    /**
+     * Project-wide site settings schema, from `createCms({ site })`. Empty
+     * when the customer didn't pass one. Carried on the payload so the admin
+     * panel can render its inputs.
+     */
+    siteSchema?: SiteSchema;
+};
+/**
+ * Result of {@link loadCms}. `cms` is the payload components consume;
+ * the three flags are mutually exclusive resolutions for the page-kind scope:
+ *
+ *  - `redirectTo` — set to a target URL when the page was replaced with a
+ *    permanent redirect; the caller should `redirect(308, redirectTo)`.
+ *  - `gone` — `true` when the page was deliberately permanently removed; the
+ *    caller should `error(410, …)`.
+ *  - `notFound` — `true` when the page-kind scope had owned params and the
+ *    adapter returned no doc and no tombstone; the caller should
+ *    `error(404, …)`.
+ *
+ * Resolution priority (handled in `resolveCmsPayload`): `redirectTo` →
+ * `gone` → `notFound` → render. Consumers should branch in that order.
+ */
+export type LoadCmsResult = {
+    cms: CmsPayload;
+    notFound: boolean;
+    gone: boolean;
+    redirectTo: string | null;
+};
+/**
+ * Pure inputs to {@link resolveCmsPayload}: everything {@link loadCms} reads
+ * from the SvelteKit `event` plus the build-time manifest, separated so tests
+ * can drive the resolver with a hand-built manifest and synthetic params.
+ */
+export type ResolveCmsPayloadArgs = {
+    manifest: CmsManifest;
+    routeId: string | null;
+    params: Record<string, string>;
+    previewKey: string | null;
+    versionKey?: string | null;
+    locale: string;
+    locales: string[];
+    adapter: CmsAdapter;
+    fetch: typeof fetch;
+    siteSchema?: SiteSchema;
+};
+/**
+ * Pure resolver: build per-scope queries from the manifest, ask the adapter
+ * for documents, and shape a {@link CmsPayload}. The page-kind doc owns a
+ * `metadata` branch on its tree; `payload.metadata` aliases that branch for
+ * `definePageMetaTags(...)`. No SvelteKit dependency — used directly by tests.
+ */
+export declare const resolveCmsPayload: (args: ResolveCmsPayloadArgs) => Promise<LoadCmsResult>;
+/**
+ * Resolve the CMS payload for the current SvelteKit request.
+ *
+ * Reads the route's scope chain from the build-time manifest, builds one
+ * query per scope with its `routeId` and bound owned `params` separately,
+ * asks `adapter.fetchDocs` for every scope's document, and shapes the result
+ * into a {@link CmsPayload} (keyed by `scopeId`) that the runtime CMS
+ * components consume via `getContext(CMS_SCOPE)` + `page.data.cms`.
+ *
+ * When `?preview=KEY` is present in the URL, the key is forwarded to the
+ * adapter as `context.previewKey`. Adapters that support release previews
+ * (e.g. `mockAdapter`) overlay any pending edits in the matching open
+ * release on top of the published content for each requested scope. Without
+ * a preview key, only published content is returned.
+ *
+ * The page-kind doc owns a `metadata` branch on its tree; `payload.metadata`
+ * aliases it for `definePageMetaTags(...)`. The doc itself is unchanged —
+ * components addressing `metadata.title` etc. read straight through.
+ *
+ * Wire it into your root `+layout.server.ts`:
+ *
+ * ```ts
+ * import { error, redirect } from '@sveltejs/kit';
+ * import { loadCms, mockAdapter } from '@velastack/cms/server';
+ *
+ * const adapter = mockAdapter({ layoutDocs: {}, pageDocs: {} });
+ *
+ * export const load = async (event) => {
+ *   const { cms, notFound, gone, redirectTo } = await loadCms(event, {
+ *     locale: 'en',
+ *     adapter
+ *   });
+ *   if (redirectTo) redirect(308, redirectTo);
+ *   if (gone) error(410, 'Gone');
+ *   if (notFound) error(404, 'Not found');
+ *   return { cms };
+ * };
+ * ```
+ */
+export declare const loadCms: (event: ServerLoadEvent, options: LoadCmsOptions) => Promise<LoadCmsResult>;

package/dist/srv/load-cms.js

@@ -0,0 +1,227 @@
+import { cmsManifest } from 'virtual:vela-cms/manifest';
+import { mergeLocaleDocs, mergeLocaleEntries } from "../components/cms/locale-merge.js";
+import { browser, building } from '$app/environment';
+const builtManifest = cmsManifest;
+const DEFAULT_ENDPOINT = '/api/cms';
+const emptyPayload = (locale, locales, endpoint, site) => ({
+    locale,
+    locales,
+    docs: {},
+    scopes: {},
+    metadata: {},
+    entries: {},
+    endpoint,
+    page: null,
+    site
+});
+const isTombstone = (r) => !!r && 'kind' in r;
+/**
+ * Pure resolver: build per-scope queries from the manifest, ask the adapter
+ * for documents, and shape a {@link CmsPayload}. The page-kind doc owns a
+ * `metadata` branch on its tree; `payload.metadata` aliases that branch for
+ * `definePageMetaTags(...)`. No SvelteKit dependency — used directly by tests.
+ */
+export const resolveCmsPayload = async (args) => {
+    const { manifest, routeId, params, previewKey, locale, locales, adapter, fetch } = args;
+    const versionKey = args.versionKey ?? null;
+    const endpoint = adapter.endpoint ?? DEFAULT_ENDPOINT;
+    const defaultLocale = locales[0] ?? locale;
+    const needsFallback = locale !== defaultLocale;
+    const siteSchema = args.siteSchema ?? {};
+    const sitePayload = async () => {
+        const tree = adapter.fetchSite
+            ? await Promise.resolve(adapter.fetchSite({ fetch, previewKey, versionKey, locale, locales }))
+            : {};
+        return { schema: siteSchema, tree: tree ?? {} };
+    };
+    if (!routeId)
+        return {
+            cms: emptyPayload(locale, locales, endpoint, await sitePayload()),
+            notFound: false,
+            gone: false,
+            redirectTo: null
+        };
+    const route = manifest.routes[routeId];
+    if (!route)
+        return {
+            cms: emptyPayload(locale, locales, endpoint, await sitePayload()),
+            notFound: false,
+            gone: false,
+            redirectTo: null
+        };
+    const buildQueries = (forLocale) => route.scopes.map((scope) => {
+        const scopeParams = {};
+        for (const p of scope.ownedParams) {
+            if (params[p] !== undefined)
+                scopeParams[p] = params[p];
+        }
+        return {
+            scopeId: scope.scopeId,
+            kind: scope.kind,
+            routeId: scope.routeId,
+            params: scopeParams,
+            fields: scope.fields,
+            locale: forLocale
+        };
+    });
+    const queries = buildQueries(locale);
+    const fallbackQueries = needsFallback ? buildQueries(defaultLocale) : null;
+    const ctx = (forLocale) => ({
+        fetch,
+        previewKey,
+        versionKey,
+        locale: forLocale,
+        locales
+    });
+    const entriesRouteIds = route.entriesRouteIds ?? [];
+    const noDocs = {};
+    const [rawDocs, fallbackDocs, entriesPairs, fallbackEntriesPairs, siteTree] = await Promise.all([
+        Promise.resolve(adapter.fetchDocs(queries, ctx(locale))),
+        fallbackQueries
+            ? Promise.resolve(adapter.fetchDocs(fallbackQueries, ctx(defaultLocale)))
+            : Promise.resolve(noDocs),
+        Promise.all(entriesRouteIds.map(async (rid) => [
+            rid,
+            await adapter.fetchEntries(rid, ctx(locale))
+        ])),
+        needsFallback
+            ? Promise.all(entriesRouteIds.map(async (rid) => [
+                rid,
+                await adapter.fetchEntries(rid, ctx(defaultLocale))
+            ]))
+            : Promise.resolve([]),
+        adapter.fetchSite
+            ? Promise.resolve(adapter.fetchSite({ fetch, previewKey, versionKey, locale, locales }))
+            : Promise.resolve({})
+    ]);
+    const site = { schema: siteSchema, tree: siteTree ?? {} };
+    // Adapter `fetchEntries` returns tombstones (redirect / gone) so the
+    // prerender path can visit redirected URLs. The consumer-facing payload
+    // drops them — `<CmsEntries>` lists shouldn't display deleted pages.
+    const isListable = (e) => !e.redirectTo && !e.gone;
+    const requestedEntries = Object.fromEntries(entriesPairs);
+    const fallbackEntries = needsFallback ? Object.fromEntries(fallbackEntriesPairs) : null;
+    const mergedEntries = mergeLocaleEntries(requestedEntries, fallbackEntries);
+    const entries = {};
+    for (const [rid, list] of Object.entries(mergedEntries)) {
+        entries[rid] = list.filter(isListable);
+    }
+    const pageQuery = queries.find((q) => q.kind === 'page');
+    // Page-kind scope can resolve to a tombstone (gone / redirect). Priority:
+    // requested-locale tombstone wins outright; otherwise requested-locale doc
+    // uses normal merge; otherwise default-locale tombstone applies; otherwise
+    // default-locale doc; otherwise notFound (when params are owned).
+    if (pageQuery) {
+        const requested = rawDocs[pageQuery.scopeId];
+        const fallback = fallbackDocs[pageQuery.scopeId];
+        let tombstone = null;
+        if (isTombstone(requested))
+            tombstone = requested;
+        else if (!requested && isTombstone(fallback))
+            tombstone = fallback;
+        if (tombstone) {
+            return {
+                cms: emptyPayload(locale, locales, endpoint, site),
+                notFound: false,
+                gone: tombstone.kind === 'gone',
+                redirectTo: tombstone.kind === 'redirect' ? tombstone.to : null
+            };
+        }
+    }
+    let pagePointer = null;
+    const requestedTrees = {};
+    const fallbackTrees = {};
+    for (const [scopeId, r] of Object.entries(rawDocs)) {
+        requestedTrees[scopeId] = isTombstone(r) ? undefined : r?.contents;
+    }
+    for (const [scopeId, f] of Object.entries(fallbackDocs)) {
+        fallbackTrees[scopeId] = isTombstone(f) ? undefined : f?.contents;
+    }
+    const docs = mergeLocaleDocs(requestedTrees, needsFallback ? fallbackTrees : null);
+    let metadata = {};
+    if (pageQuery) {
+        pagePointer = {
+            scopeId: pageQuery.scopeId,
+            routeId: pageQuery.routeId,
+            params: pageQuery.params
+        };
+        const pageDoc = docs[pageQuery.scopeId];
+        const meta = pageDoc?.metadata;
+        if (meta && typeof meta === 'object' && !Array.isArray(meta)) {
+            metadata = meta;
+        }
+    }
+    const scopes = {};
+    for (const q of queries) {
+        const { locale: _omit, ...entry } = q;
+        scopes[q.scopeId] = entry;
+    }
+    const pageScopeMissing = !!pageQuery &&
+        Object.keys(pageQuery.params).length > 0 &&
+        !(pageQuery.scopeId in rawDocs) &&
+        !(pageQuery.scopeId in fallbackDocs);
+    return {
+        cms: { locale, locales, docs, scopes, metadata, entries, endpoint, page: pagePointer, site },
+        notFound: pageScopeMissing,
+        gone: false,
+        redirectTo: null
+    };
+};
+/**
+ * Resolve the CMS payload for the current SvelteKit request.
+ *
+ * Reads the route's scope chain from the build-time manifest, builds one
+ * query per scope with its `routeId` and bound owned `params` separately,
+ * asks `adapter.fetchDocs` for every scope's document, and shapes the result
+ * into a {@link CmsPayload} (keyed by `scopeId`) that the runtime CMS
+ * components consume via `getContext(CMS_SCOPE)` + `page.data.cms`.
+ *
+ * When `?preview=KEY` is present in the URL, the key is forwarded to the
+ * adapter as `context.previewKey`. Adapters that support release previews
+ * (e.g. `mockAdapter`) overlay any pending edits in the matching open
+ * release on top of the published content for each requested scope. Without
+ * a preview key, only published content is returned.
+ *
+ * The page-kind doc owns a `metadata` branch on its tree; `payload.metadata`
+ * aliases it for `definePageMetaTags(...)`. The doc itself is unchanged —
+ * components addressing `metadata.title` etc. read straight through.
+ *
+ * Wire it into your root `+layout.server.ts`:
+ *
+ * ```ts
+ * import { error, redirect } from '@sveltejs/kit';
+ * import { loadCms, mockAdapter } from '@velastack/cms/server';
+ *
+ * const adapter = mockAdapter({ layoutDocs: {}, pageDocs: {} });
+ *
+ * export const load = async (event) => {
+ *   const { cms, notFound, gone, redirectTo } = await loadCms(event, {
+ *     locale: 'en',
+ *     adapter
+ *   });
+ *   if (redirectTo) redirect(308, redirectTo);
+ *   if (gone) error(410, 'Gone');
+ *   if (notFound) error(404, 'Not found');
+ *   return { cms };
+ * };
+ * ```
+ */
+export const loadCms = (event, options) => {
+    if (browser) {
+        throw new Error('[@velastack/cms] loadCms() is server-only — call it from `+layout.server.ts` ' +
+            'or `+page.server.ts`, not from a `+page.svelte` or universal `+page.ts`. ' +
+            "For browser-side preview/editing, use `cmsStore` from '@velastack/cms'.");
+    }
+    return resolveCmsPayload({
+        manifest: builtManifest,
+        routeId: event.route.id,
+        params: event.params,
+        previewKey: building ? null : event.url.searchParams.get('preview'),
+        versionKey: building ? null : event.url.searchParams.get('version'),
+        locale: options.locale,
+        locales: options.locales,
+        adapter: options.adapter,
+        fetch: event.fetch,
+        siteSchema: options.siteSchema
+    });
+};