@velastack/cms 0.5.0 → 0.6.0

package/README.md

@@ -42,6 +42,8 @@ CMS identity therefore can't be `(component file + field name)`. It has to be `(
 npm install @velastack/cms
 ```
 
+Requires SvelteKit 3, Svelte 5.57.1+, Vite 8.0.12+ and Node 22.17+. SvelteKit 2 projects stay on `@velastack/cms@^0.5`.
+
 ## Quick start
 
 ### 1. Register the Vite plugin
@@ -57,9 +59,20 @@ export default defineConfig({
 });
 ```
 
-The plugin reads `src/routes/` and `src/lib/` by default. Override with `cms({ routesDir, libDir })` if your project is laid out differently.
+The plugin reads `src/routes/` and `src/lib/` by default. Override with `cms({ routesDir, libDir })` if your project is laid out differently. Imports through `#lib/…` (and any other `#` subpath import in your `package.json` `imports`) are followed, as are older `$lib/…` ones.
+
+### 2. Create the CMS in `src/lib/cms.ts`
 
-### 2. Create the CMS in `$lib/cms.ts`
+SvelteKit 3 projects import `src/lib` through the `#lib` subpath import, which `sv create` (and `sv migrate sveltekit-3`) declares in `package.json`:
+
+```json
+{
+	"imports": {
+		"#lib": "./src/lib/index.js",
+		"#lib/*": "./src/lib/*"
+	}
+}
+```
 
 ```ts
 // src/lib/cms.ts
@@ -84,7 +97,7 @@ Optionally include `svelte-meta-tags` for easy page metadata handling, but it is
 // src/routes/+layout.server.ts
 import { error, redirect, type ServerLoad } from '@sveltejs/kit';
 import { defineBaseMetaTags } from 'svelte-meta-tags';
-import { loadCms } from '$lib/cms.js';
+import { loadCms } from '#lib/cms.js';
 
 export const load: ServerLoad = async (event) => {
 	const { baseMetaTags } = defineBaseMetaTags({
@@ -199,6 +212,27 @@ Only URLs that flow through `apiAdapter` responses are rewritten. If you build a
 
 If `endpoint` is omitted (e.g. when using `mockAdapter` for tests/demos), the plugin's media steps are no-ops — builds proceed exactly as before.
 
+### Static sites: `@velastack/cms/adapter`
+
+A fully static site uses the bundled adapter, a wrapper around `@sveltejs/adapter-static` (same options). SvelteKit 3 takes the adapter in `sveltekit({...})`:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { sveltekit } from '@sveltejs/kit/vite';
+import { cms } from '@velastack/cms/vite';
+import cmsAdapter from '@velastack/cms/adapter';
+
+export default defineConfig({
+	plugins: [
+		cms({ endpoint: 'https://cms.example.com/v1/projects/p1/cms' }),
+		sveltekit({ adapter: cmsAdapter({ fallback: '200.html' }) })
+	]
+});
+```
+
+After adapter-static writes the site, it adds what the admin bar needs to preview and create pages that were not prerendered: a `__fallback.json` next to each parameterized route (`rooms/__fallback.json` for `/(marketing)/rooms/[slug]`), and a `__velastack_manifest` of the creatable routes' prerendered entries injected into the `fallback` page. The manifest needs `fallback` set and the `cms()` plugin in the same build; the adapter warns if the plugin never reported.
+
 ## CMS components
 
 Every CMS component shares the same prop shape:
@@ -238,70 +272,93 @@ Rendered with `{@html}`. Edit mode swaps for a `<textarea>`.
 
 Renders an `<img>`. Edit mode shows the current image plus a URL input.
 
-### `<CmsRepeater />`
+## Structured components
+
+Hours, navigation, a team, a price list: one value with a fixed shape, edited in a slot-anchored popover and rendered by the template through a snippet. Every structured component is headless: it reads the value at `name`, normalizes it, derives the view a template needs and hands it to `children`. It never emits markup of its own.
 
 ```svelte
-<CmsRepeater name="gallery.items">
-	{#snippet children(item)}
-		<figure>
-			<CmsImage name="src" value={item.src} alt={item.caption} />
-			<figcaption>
-				<CmsText name="caption" value={item.caption} />
-			</figcaption>
-		</figure>
+<script lang="ts">
+	import { CmsHours, CmsNav, isActive } from '@velastack/cms';
+</script>
+
+<!-- In the root layout: site-wide by construction. -->
+<CmsNav name="nav.primary">
+	{#snippet children(items)}
+		{#each items as item (item.id)}
+			<a href={item.href} aria-current={isActive(item, page.url) ? 'page' : undefined}
+				>{item.label}</a
+			>
+		{/each}
 	{/snippet}
-</CmsRepeater>
+</CmsNav>
+
+<!-- On the contact page: the same value, read and written through the root scope. -->
+<CmsHours name="hours" scope="root">
+	{#snippet children(h)}
+		<p>{h.today.label}: {h.today.text} · {h.status}</p>
+		{#each h.rows as row (row.id)}<dt>{row.days}</dt>
+			<dd>{row.text}</dd>{/each}
+	{/snippet}
+</CmsHours>
 ```
 
-Iterates an array stored at `name`. Inside the snippet, pass per-item values via `value=` to bypass scope lookup. Edit mode renders the same snippet for each item plus add/remove controls and per-key inputs. `CmsRepeater` is the placeholder for the structured list components; new templates should build on `defineStructured` below.
+| Component                                                                      | Value                                                                                                                                 | Snippet receives                                                                | Helpers                                                 |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `CmsNav`                                                                       | `{ items: [{ id, label, link, children }] }`                                                                                          | items with resolved `href`                                                      | `isActive(item, url)`                                   |
+| `CmsHours`                                                                     | week grid, `exceptions`, `note`, `labels`, `timezone`                                                                                 | `rows`, `today`, `isOpenNow`, `status`, `exceptionRows` in the visitor's locale | `toOpeningHoursSpecification`                           |
+| `CmsContact`                                                                   | `name`, `address`, `phones`, `emails`, `whatsapp`, `directionsUrl`, `geo`, `labels`                                                   | plus `telHref`, `mailto`, `whatsappHref`, `mapsHref`, `formattedAddress`        | `toPostalAddress`                                       |
+| `CmsSocialLinks`                                                               | `{ items: [{ id, platform, url, label }] }`                                                                                           | items with `name` (label or platform name)                                      | `toSameAs`, `SOCIAL_PLATFORMS`                          |
+| `CmsCollection`                                                                | rooms, services, tours: title, summary, body, image, gallery, price, link, tags, features, `details` key-value list, featured, hidden | visible items with `href`; props `limit`, `featured`, `tag` slice them          | `formatCollectionPrice`, `collectionTags`, `toItemList` |
+| `CmsTeam`                                                                      | name, role, rich bio, photo, email, phone, profile links                                                                              | members                                                                         |                                                         |
+| `CmsTestimonials`                                                              | rich quote, author, role, company, photo, rating, source, date                                                                        | testimonials                                                                    | `toReview`                                              |
+| `CmsPricing`                                                                   | `currency`, `labels.custom`, tiers with a feature checklist and a CTA                                                                 | tiers with `priceText` and `href`                                               | `formatPrice`                                           |
+| `CmsFaq`                                                                       | question, rich answer                                                                                                                 | questions                                                                       | `toFaqPage`                                             |
+| `CmsStats`, `CmsSteps`, `CmsTimeline`, `CmsGallery`, `CmsLogos`, `CmsSchedule` | fixed list presets                                                                                                                    | items                                                                           | `logosView`, `scheduleByDay`                            |
 
-## Structured components
+Templates use only these exports; there is no open item schema. A shape outside the presets is a new preset in the package. `fallback` takes the full value or a bare item list and is normalized like a stored value, so a hand-written seed with missing fields is safe. Prices, times, dates and day names format in the visitor's locale; `isOpenNow` is computed when the page renders, so a prerendered page shows the state at build time.
 
-Hours, team, testimonials and the like are one value with a fixed shape, edited in a slot-anchored popover and rendered by the template through a snippet. The package ships the pieces a structured component is made of; the components themselves come with the editor-components release.
+Every value type (`CmsHoursValue`, `NavItem`, …), schema (`cmsHours`, …) and JSON-LD helper is exported from the package root.
 
-```ts
-// hours.ts — the value's rules
-import { defineStructured, registerStructured, asItems, asString } from '@velastack/cms';
+### Building one
+
+The package ships the pieces a structured component is made of, and the components above are built from nothing else.
 
-export const hours = registerStructured(
-	defineStructured<Hours>({
-		component: 'CmsHours', // canonical export name, recorded in the manifest
-		version: 1, // written as `v` on every value
-		translatable: ['note'], // root fields that translate
-		items: { key: 'days', translatable: ['label'] }, // the list and its translatable fields
-		normalize: (raw) => ({ v: 1, note: asString(raw?.note), days: asItems(raw?.days, …) }),
-		empty: () => ({ v: 1, note: '', days: [] })
-	})
-);
+```ts
+// The value's rules: a versioned shape, its translatable strings, and the form the popover draws.
+import { defineForm, asItems, asString } from '@velastack/cms';
+
+export const cmsFaq = defineForm<CmsFaqValue>({
+	component: 'CmsFaq', // canonical export name, recorded in the manifest
+	label: 'FAQ', // popover header
+	version: 1, // written as `v` on every value
+	translatable: [], // root fields that translate (dotted paths allowed: 'labels.closed')
+	items: { key: 'items', translatable: ['question', 'answer'] }, // lists and their translatable fields; nest `items` for lists inside items
+	normalize: (raw) => ({ v: 1, items: asItems(raw?.items, …) }),
+	empty: () => ({ v: 1, items: [] }),
+	fields: [{ key: 'items', type: 'list', label: 'Questions', itemLabel: 'question', titleKey: 'question', blank: () => ({ question: '', answer: '' }), fields: [
+		{ key: 'question', label: 'Question', type: 'text' },
+		{ key: 'answer', label: 'Answer', type: 'html' }
+	] }]
+});
 ```
 
 ```svelte
-<!-- cms-hours.svelte — the display component -->
+<!-- The display component, inside the package: the generic one, given the schema and a view function. -->
 <script lang="ts">
-	import { useCmsField } from '@velastack/cms';
-	let { name, scope, fallback, children } = $props();
-	const field = useCmsField(
-		() => ({ name, scope }),
-		(raw) => hours.read(raw, fallback)
-	);
+	import Structured from './cms-structured.svelte'; // src/lib/components/cms, inside the package
+	let { name, scope, fallback, value, children } = $props();
 </script>
 
-{#if field.editable}
-	{#await import('./cms-hours-editable.svelte') then { default: Editable }}
-		<Editable {field} {children} />
-	{/await}
-{:else}
-	{@render children(field.current)}
-{/if}
+<Structured schema={cmsFaq} {name} {scope} {fallback} {value} view={faqView} {children} />
 ```
 
-The editable sibling wraps `StructuredEditorPopover` from `@velastack/cms/editor` (also `FieldInput`, `ReorderButtons`, the Popover / Tabs / Switch / Checkbox / Sheet primitives and `CmsMediaPicker`), passes a `preview` snippet and an `editor` snippet over a local draft, and the popover commits on **Done**. Edit mode is page-wide; the bar's Save flushes the draft.
+Field types: `text`, `long-string`, `html` (TipTap), `number`, `boolean`, `date`, `time`, `url`, `image` and `images` (media picker, alt text), `enum`, `link` (page picker or URL, new tab), `strings` (one per line), `rating`, `list` (collapsible cards with reorder). `group` puts a field in a tab; `half` shares a row with the next field. A bespoke editor (the hours week grid) wraps `StructuredEditorPopover` from `@velastack/cms/editor` and renders `FieldsForm` for the rest; `FieldInput`, `ListField`, `LinkInput`, `RichTextInput`, `ReorderButtons` and the Popover / Tabs / Switch / Checkbox / Sheet primitives are exported there too. The popover commits on **Done**; edit mode is page-wide and the bar's Save flushes the draft.
 
 Rules every structured value follows (`core/structured.ts`):
 
 - **Whole-object writes, explicit `null` clears.** Components never patch a leaf; they write the full `{ v, … }` object. Cleared fields are `null`.
-- **List items carry a stable `id`** (`newItemId()`); reorder and delete work because arrays replace wholesale on merge.
-- **Localisation is a string overlay.** The default locale stores the full value at `<name>`; every other locale stores only strings at `<name>.$t.<id>.<field>` (`_` is the id for root fields). `read()` folds the overlay in, structure never forks between languages, and the popover's locale tabs write only the overlay. The Locales panel counts translatable strings per locale for every structured usage on the current route.
+- **List items carry a stable `id`** (`newItemId()`) at every nesting level; reorder and delete work because arrays replace wholesale on merge.
+- **Localisation is a string overlay.** The default locale stores the full value at `<name>`; every other locale stores only strings at `<name>.$t.<id>.<field>` (`_` is the id for root fields, `field` may be a dotted path, and a string array translates per index as `tags.0`). `read()` folds the overlay in, structure never forks between languages, and the popover's locale tabs write only the overlay. The Locales panel counts translatable strings per locale for every structured usage on the current route.
 
 ### `<CmsEntries />`
 
@@ -347,7 +404,7 @@ A component is treated as a CMS component if **any** of the following hold:
 
    Use it from any route: `<CmsLink name="hero.cta" />`. The plugin picks up `hero.cta` as a field on the page's scope; no plugin config edit required.
 
-2. **It's a named export from your local `src/lib/components/cms/index.{ts,js}` barrel.** Re-export your component there if you prefer a single import path..
+2. **It's a named export from your local `src/lib/components/cms/index.{ts,js}` barrel** (imported as `#lib/components/cms/index.js`). Re-export your component there if you prefer a single import path.
 
 3. **It's imported from the `@velastack/cms` package itself.** Every named import from `@velastack/cms` is a CMS component, whether or not the bundler resolved the package.
 

package/dist/backend/index.d.ts

@@ -7,7 +7,7 @@
  * export const cms = createCmsBackend();
  *
  * // src/routes/cms/[...path]/+server.ts
- * import { cms } from '../server/cms';
+ * import { cms } from '../server/cms.js';
  * export const prerender = false;
  * export const fallback = cms.handler;
  * ```
@@ -25,10 +25,12 @@
  * default; enabling it with an `origin` predicate that returns `true`
  * unconditionally lets any site drive the mutating endpoints with a signed-in
  * editor's cookie, because SvelteKit's CSRF check only guards form content
- * types and these are JSON. And SvelteKit *does* guard `multipart/form-data`,
- * so a cross-origin `POST /media` needs the site's origin in
- * `kit.csrf.trustedOrigins` — that check is production-only, so it will not
- * show up in `vela dev`.
+ * types (and, since Kit 3, requests with no content type) and these are JSON.
+ * The admin bar sends every mutation with a JSON content type for that reason.
+ * SvelteKit *does* guard `multipart/form-data`, so a cross-origin
+ * `POST /media` needs the site's origin in the backend app's
+ * `sveltekit({ csrf: { trustedOrigins: ['https://site.example'] } })` — that
+ * check is production-only, so it will not show up in `vela dev`.
  *
  * The session cookie is scoped to the mount path (`/cms`, or
  * `/v1/projects/<id>/cms`), so several projects on one origin hold independent

package/dist/backend/index.js

@@ -7,7 +7,7 @@
  * export const cms = createCmsBackend();
  *
  * // src/routes/cms/[...path]/+server.ts
- * import { cms } from '../server/cms';
+ * import { cms } from '../server/cms.js';
  * export const prerender = false;
  * export const fallback = cms.handler;
  * ```
@@ -25,10 +25,12 @@
  * default; enabling it with an `origin` predicate that returns `true`
  * unconditionally lets any site drive the mutating endpoints with a signed-in
  * editor's cookie, because SvelteKit's CSRF check only guards form content
- * types and these are JSON. And SvelteKit *does* guard `multipart/form-data`,
- * so a cross-origin `POST /media` needs the site's origin in
- * `kit.csrf.trustedOrigins` — that check is production-only, so it will not
- * show up in `vela dev`.
+ * types (and, since Kit 3, requests with no content type) and these are JSON.
+ * The admin bar sends every mutation with a JSON content type for that reason.
+ * SvelteKit *does* guard `multipart/form-data`, so a cross-origin
+ * `POST /media` needs the site's origin in the backend app's
+ * `sveltekit({ csrf: { trustedOrigins: ['https://site.example'] } })` — that
+ * check is production-only, so it will not show up in `vela dev`.
  *
  * The session cookie is scoped to the mount path (`/cms`, or
  * `/v1/projects/<id>/cms`), so several projects on one origin hold independent

package/dist/backend/types.d.ts

@@ -138,7 +138,7 @@ export type CmsBackendOptions = {
      *
      * Enabling this is a security decision, not a convenience one: the session
      * cookie is credentialed and the JSON mutation endpoints are not covered by
-     * SvelteKit's CSRF check (it only guards form content types). An `origin`
+     * SvelteKit's CSRF check (it only guards form and missing content types). An `origin`
      * predicate that returns `true` unconditionally lets any site on the
      * internet drive those endpoints with a signed-in editor's cookie. Allowlist
      * the origins you actually serve.

package/dist/components/admin-bar/admin-bar-internal.svelte

@@ -1,11 +1,5 @@
 <script lang="ts">
-	import {
-		afterNavigate,
-		beforeNavigate,
-		goto,
-		invalidateAll,
-		replaceState
-	} from '$app/navigation';
+	import { afterNavigate, beforeNavigate, goto, refreshAll } from '$app/navigation';
 	import { page } from '$app/state';
 	import { pages } from 'virtual:vela-cms/pages';
 	import { cmsStore, type PageDeleteOutcome } from '../cms/cms-store.svelte.js';
@@ -14,6 +8,7 @@
 	import CssRoot from './css-root.svelte';
 	import { adminBarTheme, type AdminBarTheme } from './theme.svelte.js';
 	import type { CmsDeployState } from '../../core/wire.js';
+	import { cmsFetch } from '../../core/cms-fetch.js';
 	import DeletePageDialog, {
 		type DeletePageMode,
 		type RedirectTarget
@@ -186,7 +181,7 @@
 
 	const previewUrl = $derived.by(() => {
 		if (versionKey) {
-			const url = new URL(page.url);
+			const url = new URL(page.url.href);
 			url.searchParams.delete('edit');
 			url.searchParams.delete('preview');
 			url.searchParams.set('version', versionKey);
@@ -194,7 +189,7 @@
 		}
 		const key = previewKey;
 		if (!key) return '';
-		const url = new URL(page.url);
+		const url = new URL(page.url.href);
 		url.searchParams.delete('edit');
 		url.searchParams.set('preview', key);
 		return url.toString();
@@ -211,7 +206,7 @@
 	};
 
 	const setPreviewParam = async (key: string | null, opts: { replace?: boolean } = {}) => {
-		const url = new URL(page.url);
+		const url = new URL(page.url.href);
 		const current = url.searchParams.get('preview');
 		url.searchParams.delete('edit');
 		if (key) {
@@ -223,14 +218,14 @@
 		}
 		const path = url.pathname + url.search + url.hash;
 		if (opts.replace) {
-			replaceState(path, page.state);
+			await goto(path, { shallow: true, replace: true, state: page.state });
 		} else {
-			await goto(path, { keepFocus: true, noScroll: true });
+			await goto(path, { reset: false });
 		}
 	};
 
 	const setVersionParam = async (key: string | null, opts: { replace?: boolean } = {}) => {
-		const url = new URL(page.url);
+		const url = new URL(page.url.href);
 		const current = url.searchParams.get('version');
 		url.searchParams.delete('edit');
 		url.searchParams.delete('preview');
@@ -243,14 +238,14 @@
 		}
 		const path = url.pathname + url.search + url.hash;
 		if (opts.replace) {
-			replaceState(path, page.state);
+			await goto(path, { shallow: true, replace: true, state: page.state });
 		} else {
-			await goto(path, { keepFocus: true, noScroll: true });
+			await goto(path, { reset: false });
 			// Force the server load to re-fetch. SvelteKit's URL tracking
 			// doesn't always pick up our `?version=` access (it lives behind
 			// the `loadCms` helper) — visible on Exit, where we'd otherwise
 			// keep showing the past release's `page.data.cms.docs`.
-			await invalidateAll();
+			await refreshAll();
 		}
 	};
 
@@ -264,7 +259,7 @@
 	// (and on static-export sites with no server load to re-run). Like the
 	// other gating params, we strip the param when `null`.
 	const setLocaleParam = async (locale: string | null, opts: { replace?: boolean } = {}) => {
-		const url = new URL(page.url);
+		const url = new URL(page.url.href);
 		const current = url.searchParams.get('locale');
 		if (locale) {
 			if (current === locale) return;
@@ -275,18 +270,18 @@
 		}
 		const path = url.pathname + url.search + url.hash;
 		if (opts.replace) {
-			replaceState(path, page.state);
+			await goto(path, { shallow: true, replace: true, state: page.state });
 			return;
 		}
 		if (!locale) {
 			clearingLocale = true;
 			try {
-				await goto(path, { keepFocus: true, noScroll: true });
+				await goto(path, { reset: false });
 			} finally {
 				clearingLocale = false;
 			}
 		} else {
-			await goto(path, { keepFocus: true, noScroll: true });
+			await goto(path, { reset: false });
 		}
 	};
 
@@ -333,7 +328,7 @@
 	// Until then, the overlay-sync effect must NOT strip `?preview=` from the
 	// URL — `cmsStore.openRelease` is null pre-fetch, but that's "unknown",
 	// not "no draft". Without this gate, a hard refresh on `?preview=<key>`
-	// would treat the param as stale and replaceState it away.
+	// would treat the param as stale and shallow-replace it away.
 	let openReleaseFetched = $state(false);
 
 	// On mount and on subsequent URL/store changes: derive what to do (URL sync,
@@ -411,6 +406,7 @@
 	// appended; already-correct nav targets pass through unchanged. Full-page
 	// unloads (`willUnload`) and external/hash-only navs bypass.
 	beforeNavigate((nav) => {
+		if (nav.shallow) return;
 		if (nav.type === 'leave' || nav.willUnload) return;
 		if (!nav.to) return;
 		if (nav.to.url.origin !== location.origin) return;
@@ -434,10 +430,7 @@
 				nav.cancel();
 				const url = new URL(nav.to.url);
 				carryLocaleOnto(url);
-				void goto(url.pathname + url.search + url.hash, {
-					keepFocus: true,
-					noScroll: true
-				});
+				void goto(url.pathname + url.search + url.hash, { reset: false });
 				return;
 			}
 			// Target has no `?version=`. If we're exiting on purpose, let the nav
@@ -448,10 +441,7 @@
 			url.searchParams.delete('preview');
 			url.searchParams.set('version', versionKey);
 			carryLocaleOnto(url);
-			void goto(url.pathname + url.search + url.hash, {
-				keepFocus: true,
-				noScroll: true
-			});
+			void goto(url.pathname + url.search + url.hash, { reset: false });
 			return;
 		}
 
@@ -462,10 +452,7 @@
 			nav.cancel();
 			const url = new URL(nav.to.url);
 			carryLocaleOnto(url);
-			void goto(url.pathname + url.search + url.hash, {
-				keepFocus: true,
-				noScroll: true
-			});
+			void goto(url.pathname + url.search + url.hash, { reset: false });
 			return;
 		}
 
@@ -477,23 +464,26 @@
 		const url = new URL(nav.to.url);
 		if (key) url.searchParams.set('preview', key);
 		carryLocaleOnto(url);
-		void goto(url.pathname + url.search + url.hash, {
-			keepFocus: true,
-			noScroll: true
-		});
+		void goto(url.pathname + url.search + url.hash, { reset: false });
 	});
 
 	// Re-apply the overlay on every internal navigation. SvelteKit may strip
 	// the gating param when nav targets aren't preserve-params links, so we
-	// reapply it via replaceState too. Merge (not reset) so unchanged-layout
+	// reapply it via a shallow replace too. Merge (not reset) so unchanged-layout
 	// overlays keep showing while new-page-scope fetches resolve.
-	afterNavigate(() => {
+	afterNavigate(({ shallow }) => {
+		if (shallow) return;
+
 		if (versionKey) {
-			const url = new URL(page.url);
+			const url = new URL(page.url.href);
 			if (url.searchParams.get('version') !== versionKey) {
 				url.searchParams.delete('preview');
 				url.searchParams.set('version', versionKey);
-				replaceState(url.pathname + url.search + url.hash, page.state);
+				void goto(url.pathname + url.search + url.hash, {
+					shallow: true,
+					replace: true,
+					state: page.state
+				});
 			}
 			// `reset` so a nav from one release to another wipes the prior
 			// snapshot's overlay before merging in the new one — otherwise
@@ -522,10 +512,14 @@
 			cmsStore.clearOverlay();
 			return;
 		}
-		const url = new URL(page.url);
+		const url = new URL(page.url.href);
 		if (url.searchParams.get('preview') !== key) {
 			url.searchParams.set('preview', key);
-			replaceState(url.pathname + url.search + url.hash, page.state);
+			void goto(url.pathname + url.search + url.hash, {
+				shallow: true,
+				replace: true,
+				state: page.state
+			});
 		}
 		void cmsStore.loadAndApplyOverlay(endpoint, currentScopes(), key, { locale: currentLocale });
 		void cmsStore.loadAndApplyEntriesOverlay(endpoint, currentEntriesRouteIds(), key, {
@@ -684,7 +678,7 @@
 		deploying = true;
 		deployError = null;
 		try {
-			const res = await fetch(`${endpoint}/deploy`, { method: 'POST', credentials: 'include' });
+			const res = await cmsFetch(`${endpoint}/deploy`, { method: 'POST' });
 			if (!res.ok) {
 				deployError = (await res.text()) || 'Could not start the deploy.';
 				return;
@@ -925,9 +919,8 @@
 
 	const onRegeneratePreviewKey = async () => {
 		if (versionKey && versionRelease) {
-			const res = await fetch(`${endpoint}/release/history/${versionRelease.id}/preview-key`, {
-				method: 'POST',
-				credentials: 'include'
+			const res = await cmsFetch(`${endpoint}/release/history/${versionRelease.id}/preview-key`, {
+				method: 'POST'
 			});
 			if (!res.ok) return;
 			const data = (await res.json()) as { preview_key: string };
@@ -948,9 +941,8 @@
 			return;
 		}
 
-		const res = await fetch(`${endpoint}/release/preview-key`, {
-			method: 'POST',
-			credentials: 'include'
+		const res = await cmsFetch(`${endpoint}/release/preview-key`, {
+			method: 'POST'
 		});
 		if (!res.ok) return;
 		await cmsStore.fetchOpenRelease(endpoint);
@@ -959,9 +951,8 @@
 
 	const onDiscardAllChanges = async () => {
 		if (!confirm('Discard all unpublished changes in your working copy?')) return;
-		const res = await fetch(`${endpoint}/release/discard`, {
-			method: 'POST',
-			credentials: 'include'
+		const res = await cmsFetch(`${endpoint}/release/discard`, {
+			method: 'POST'
 		});
 		if (!res.ok) return;
 		cmsStore.setOpenRelease(null);
@@ -1171,6 +1162,7 @@
 		const sourceContents: Record<string, unknown> = res.ok
 			? ((await res.json()) as { contents: Record<string, unknown> }).contents
 			: {};
+
 		const { metadata: meta, ...rest } = sourceContents as { metadata?: unknown } & Record<
 			string,
 			unknown
@@ -1179,6 +1171,7 @@
 			meta && typeof meta === 'object' && !Array.isArray(meta)
 				? (meta as Record<string, unknown>)
 				: {};
+
 		closeAllPanels();
 		duplicateSource = { tree: rest, metadata: sourceMetadata };
 		newDialog = config;
@@ -1261,7 +1254,7 @@
 			duplicateSource = null;
 			pagesOpen = false;
 			cmsStore.isEditing = true;
-			await goto(url, { keepFocus: true, noScroll: true });
+			await goto(url, { reset: false });
 		} finally {
 			newPageCreating = false;
 		}
@@ -1320,7 +1313,7 @@
 								<KbdShortcut keys="⌘E" class={menuShortcutClass} />
 							</Menubar.Item>
 							<Menubar.Item class={menuItemClass} onSelect={onOpenSeo}>
-								SEO &amp; Metadata
+								SEO & Metadata
 								<KbdShortcut keys="⌘I" class={menuShortcutClass} />
 							</Menubar.Item>
 							<Menubar.Separator class={menuSeparatorClass} />
@@ -1394,7 +1387,7 @@
 								onSelect={onOpenPublish}
 								disabled={counts.total === 0}
 							>
-								Review &amp; Publish…
+								Review & Publish…
 								{#if counts.total > 0}
 									<span class="vela:ml-auto vela:flex vela:items-center vela:gap-2">
 										<span
@@ -1410,9 +1403,11 @@
 									<KbdShortcut keys="⌘P" class={menuShortcutClass} />
 								{/if}
 							</Menubar.Item>
-							<Menubar.Item class={menuItemClass} onSelect={onShareLink} disabled={!previewUrl}>
-								Share Preview Link…
-							</Menubar.Item>
+
+							<Menubar.Item class={menuItemClass} onSelect={onShareLink} disabled={!previewUrl}
+								>Share Preview Link…</Menubar.Item
+							>
+
 							<Menubar.Item
 								class={menuItemDestructiveClass}
 								onSelect={onDiscardAllChanges}