@aphexcms/cms-core 9.2.0 → 9.2.1

package/dist/components/admin/fields/ImageField.svelte

@@ -211,21 +211,25 @@
 		assetData?.originalFilename || assetData?.filename || value?.asset?._ref || 'Image'
 	);
 
-	// Alt text — stored on the asset record, not on the ImageValue
-	let altText = $state('');
-	let altSaveTimer: ReturnType<typeof setTimeout> | null = null;
-
-	// Sync altText from asset data when it loads
+	// Two layers of alt text:
+	//  • Default — stored on the ASSET, shared across every placement. Set it once and
+	//    it applies everywhere the image is used.
+	//  • Override — stored on THIS image value, for when one spot needs a different
+	//    description. Render precedence is `value.alt || asset.alt`.
+	// The override is also what carries visual-editing stega.
+	let assetAltText = $state('');
+	let assetAltTimer: ReturnType<typeof setTimeout> | null = null;
+
+	// Sync the default from the loaded asset record.
 	$effect(() => {
-		altText = assetData?.alt || '';
+		assetAltText = assetData?.alt || '';
 	});
 
-	function updateAltText(newAlt: string) {
-		altText = newAlt;
-
-		// Debounce the API call
-		if (altSaveTimer) clearTimeout(altSaveTimer);
-		altSaveTimer = setTimeout(async () => {
+	function updateAssetAlt(newAlt: string) {
+		assetAltText = newAlt;
+		// Debounce the asset-update API call.
+		if (assetAltTimer) clearTimeout(assetAltTimer);
+		assetAltTimer = setTimeout(async () => {
 			const assetId = value?.asset?._ref;
 			if (!assetId) return;
 			try {
@@ -236,6 +240,17 @@
 		}, 800);
 	}
 
+	function updateOverrideAlt(newAlt: string) {
+		if (!value) return;
+		onUpdate({ ...value, alt: newAlt || undefined });
+	}
+
+	// Whether to reveal the per-placement override input.
+	let showOverride = $state(false);
+	$effect(() => {
+		if (value?.alt) showOverride = true;
+	});
+
 	// Download image
 	function downloadImage() {
 		if (previewUrl) {
@@ -272,7 +287,7 @@
 				{:else if previewUrl}
 					<img
 						src={previewUrl}
-						alt={assetData?.alt || displayName}
+						alt={value?.alt || assetData?.alt || displayName}
 						class="h-full w-full object-cover"
 						loading="lazy"
 					/>
@@ -299,7 +314,7 @@
 				{:else if previewUrl}
 					<img
 						src={previewUrl}
-						alt={assetData?.alt || displayName}
+						alt={value?.alt || assetData?.alt || displayName}
 						class="h-full w-full object-cover"
 						loading="lazy"
 					/>
@@ -389,7 +404,7 @@
 					{:else if previewUrl}
 						<img
 							src={previewUrl}
-							alt={assetData?.alt || 'Uploaded image'}
+							alt={value?.alt || assetData?.alt || 'Uploaded image'}
 							class="h-full w-full object-contain"
 							loading="lazy"
 						/>
@@ -453,18 +468,61 @@
 				{/if}
 			</div>
 
-			<!-- Alt text field -->
-			<div class="border-border space-y-1.5 border-t p-3">
-				<label class="text-sm font-medium" for="alt-{field.name}">Alt text</label>
-				<p class="text-muted-foreground text-xs">Describe the image for accessibility and SEO</p>
-				<Input
-					id="alt-{field.name}"
-					type="text"
-					placeholder="Describe this image..."
-					value={altText}
-					oninput={(e) => updateAltText(e.currentTarget.value)}
-					disabled={isReadOnly}
-				/>
+			<!-- Alt text — asset-level default + optional per-placement override -->
+			<div class="border-border space-y-2 border-t p-3">
+				<div class="space-y-1.5">
+					<label class="text-sm font-medium" for="alt-{field.name}">Alt text</label>
+					<p class="text-muted-foreground text-xs">
+						Describes the image everywhere it's used (accessibility &amp; SEO).
+					</p>
+					<Input
+						id="alt-{field.name}"
+						type="text"
+						placeholder="Describe this image..."
+						value={assetAltText}
+						oninput={(e) => updateAssetAlt(e.currentTarget.value)}
+						disabled={isReadOnly}
+					/>
+				</div>
+
+				{#if showOverride}
+					<div class="space-y-1.5">
+						<div class="flex items-center justify-between">
+							<label
+								class="text-muted-foreground text-xs font-medium"
+								for="alt-override-{field.name}">Override for this placement</label
+							>
+							{#if !isReadOnly}
+								<button
+									type="button"
+									class="text-muted-foreground hover:text-foreground text-xs underline-offset-2 hover:underline"
+									onclick={() => {
+										updateOverrideAlt('');
+										showOverride = false;
+									}}
+								>
+									Remove
+								</button>
+							{/if}
+						</div>
+						<Input
+							id="alt-override-{field.name}"
+							type="text"
+							placeholder={assetAltText || 'Describe this image...'}
+							value={value?.alt ?? ''}
+							oninput={(e) => updateOverrideAlt(e.currentTarget.value)}
+							disabled={isReadOnly}
+						/>
+					</div>
+				{:else if !isReadOnly}
+					<button
+						type="button"
+						class="text-muted-foreground hover:text-foreground text-xs underline-offset-2 hover:underline"
+						onclick={() => (showOverride = true)}
+					>
+						+ Override for this placement
+					</button>
+				{/if}
 			</div>
 		</div>
 	{:else}

package/dist/components/admin/fields/ImageField.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ImageField.svelte.d.ts","sourceRoot":"","sources":["../../../../src/lib/components/admin/fields/ImageField.svelte.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,IAAI,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAmB1E,UAAU,KAAK;IACd,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,KAAK,IAAI,CAAC;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AA4cF,QAAA,MAAM,UAAU,2CAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}
+{"version":3,"file":"ImageField.svelte.d.ts","sourceRoot":"","sources":["../../../../src/lib/components/admin/fields/ImageField.svelte.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,IAAI,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAmB1E,UAAU,KAAK;IACd,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,KAAK,IAAI,CAAC;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAofF,QAAA,MAAM,UAAU,2CAAwC,CAAC;AACzD,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAChD,eAAe,UAAU,CAAC"}

package/dist/components/admin/fields/richtext/ImageBlockModal.svelte

@@ -0,0 +1,133 @@
+<script lang="ts">
+	import { Button } from '@aphexcms/ui/shadcn/button';
+	import { Input } from '@aphexcms/ui/shadcn/input';
+	import { Image as ImageIcon, Upload, Trash2, X } from '@lucide/svelte';
+	import { assets } from '../../../../api/assets';
+
+	interface Props {
+		open: boolean;
+		assetRef?: string;
+		alt: string;
+		readonly?: boolean;
+		onAltChange: (alt: string) => void;
+		onReplace: () => void;
+		onRemove: () => void;
+		onClose: () => void;
+	}
+
+	let {
+		open,
+		assetRef,
+		alt,
+		readonly = false,
+		onAltChange,
+		onReplace,
+		onRemove,
+		onClose
+	}: Props = $props();
+
+	const assetPromise = $derived(assetRef ? assets.getById(assetRef) : null);
+
+	function handleBackdropClick(e: MouseEvent) {
+		if (e.target === e.currentTarget) onClose();
+	}
+
+	function handleKeydown(e: KeyboardEvent) {
+		if (e.key === 'Escape') onClose();
+	}
+</script>
+
+{#if open}
+	<!-- svelte-ignore a11y_no_static_element_interactions -->
+	<div
+		class="bg-background/80 absolute inset-0 z-50 flex items-center justify-center p-4 lg:p-6"
+		onclick={handleBackdropClick}
+		onkeydown={handleKeydown}
+		role="button"
+		tabindex="-1"
+	>
+		<!-- svelte-ignore a11y_no_static_element_interactions -->
+		<div
+			class="border-border bg-background w-full max-w-lg overflow-hidden rounded-lg border shadow-lg"
+			onclick={(e) => e.stopPropagation()}
+			onkeydown={(e) => e.stopPropagation()}
+		>
+			<div class="border-border flex items-center justify-between border-b px-4 py-2">
+				<span class="text-sm font-medium">Edit image</span>
+				<Button variant="ghost" size="icon" class="h-7 w-7" onclick={onClose}>
+					<X class="h-3.5 w-3.5" />
+				</Button>
+			</div>
+
+			<div class="space-y-3 p-4">
+				<!-- Preview -->
+				<div
+					class="bg-muted flex items-center justify-center overflow-hidden rounded-md"
+					style="aspect-ratio: 16 / 9;"
+				>
+					{#if assetPromise}
+						{#await assetPromise}
+							<div
+								class="border-primary h-5 w-5 animate-spin rounded-full border-2 border-t-transparent"
+							></div>
+						{:then result}
+							{#if result.success && result.data?.url}
+								<img src={result.data.url} {alt} class="h-full w-full object-contain" />
+							{:else}
+								<div class="text-muted-foreground flex flex-col items-center gap-1">
+									<ImageIcon class="h-8 w-8" />
+									<span class="text-xs">Image not found</span>
+								</div>
+							{/if}
+						{:catch}
+							<div class="text-muted-foreground flex flex-col items-center gap-1">
+								<ImageIcon class="h-8 w-8" />
+								<span class="text-xs">Failed to load</span>
+							</div>
+						{/await}
+					{:else}
+						<div class="text-muted-foreground flex flex-col items-center gap-1">
+							<ImageIcon class="h-8 w-8" />
+							<span class="text-xs">No image</span>
+						</div>
+					{/if}
+				</div>
+
+				<!-- Alt text (per-placement override of the asset's default alt) -->
+				<div class="space-y-1.5">
+					<label class="text-sm font-medium" for="image-block-alt">Alt text</label>
+					<p class="text-muted-foreground text-xs">
+						Overrides the image's default alt for this spot. Leave blank to use the default.
+					</p>
+					<Input
+						id="image-block-alt"
+						type="text"
+						placeholder="Describe this image..."
+						value={alt}
+						oninput={(e) => onAltChange(e.currentTarget.value)}
+						disabled={readonly}
+					/>
+				</div>
+
+				<!-- Actions -->
+				{#if !readonly}
+					<div class="flex items-center justify-between gap-2 pt-1">
+						<Button variant="outline" size="sm" onclick={onReplace}>
+							<Upload class="mr-1.5 h-4 w-4" />
+							Replace
+						</Button>
+						<Button
+							variant="ghost"
+							size="sm"
+							class="text-destructive hover:text-destructive"
+							onclick={onRemove}
+						>
+							<Trash2 class="mr-1.5 h-4 w-4" />
+							Remove
+						</Button>
+					</div>
+				{/if}
+			</div>
+		</div>
+	</div>
+{/if}

package/dist/components/admin/fields/richtext/ImageBlockModal.svelte.d.ts

@@ -0,0 +1,14 @@
+interface Props {
+    open: boolean;
+    assetRef?: string;
+    alt: string;
+    readonly?: boolean;
+    onAltChange: (alt: string) => void;
+    onReplace: () => void;
+    onRemove: () => void;
+    onClose: () => void;
+}
+declare const ImageBlockModal: import("svelte").Component<Props, {}, "">;
+type ImageBlockModal = ReturnType<typeof ImageBlockModal>;
+export default ImageBlockModal;
+//# sourceMappingURL=ImageBlockModal.svelte.d.ts.map

package/dist/components/admin/fields/richtext/ImageBlockModal.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImageBlockModal.svelte.d.ts","sourceRoot":"","sources":["../../../../../src/lib/components/admin/fields/richtext/ImageBlockModal.svelte.ts"],"names":[],"mappings":"AASC,UAAU,KAAK;IACd,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,IAAI,CAAC;CACpB;AAoGF,QAAA,MAAM,eAAe,2CAAwC,CAAC;AAC9D,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,eAAe,eAAe,CAAC"}

package/dist/components/admin/fields/richtext/PortableTextImageView.svelte

@@ -19,7 +19,7 @@
 
 <!-- svelte-ignore a11y_click_events_have_key_events -->
 <!-- svelte-ignore a11y_no_static_element_interactions -->
-<div class="image-block-view group" class:selected onclick={onEdit}>
+<div class="image-block-view group" class:selected data-pt-image-edit onclick={onEdit}>
 	{#if assetPromise}
 		{#await assetPromise}
 			<div class="image-block-placeholder">
@@ -29,7 +29,7 @@
 			</div>
 		{:then result}
 			{#if result.success && result.data?.url}
-				<img src={result.data.url} alt={result.data.alt || ''} class="image-block-img" />
+				<img src={result.data.url} alt={(data?.alt as string) || ''} class="image-block-img" />
 			{:else}
 				<div class="image-block-placeholder">
 					<ImageIcon class="text-muted-foreground h-8 w-8" />

package/dist/components/admin/fields/richtext/RichtextField.svelte

@@ -35,7 +35,9 @@
 	import type { ArrayField as ArrayFieldType, SchemaType } from '../../../../types/schemas';
 	import { getSchemaContext } from '../../../../schema-context.svelte';
 	import { getSchemaByName } from '../../../../schema-utils/utils';
+	import { getRichtextEditorRegistry } from '../../../../richtext-context.svelte.js';
 	import ObjectModal from '../../ObjectModal.svelte';
+	import ImageBlockModal from './ImageBlockModal.svelte';
 	import AssetBrowserModal from '../../AssetBrowserModal.svelte';
 	import * as Tooltip from '@aphexcms/ui/shadcn/tooltip';
 	import { Image as ImageIcon } from '@lucide/svelte';
@@ -190,8 +192,9 @@
 
 	function handleEditBlock(attrs: { _type: string; _key: string; data: Record<string, unknown> }) {
 		if (attrs._type === 'image') {
-			editingNodeKey = attrs._key;
-			showAssetBrowser = true;
+			editingImageKey = attrs._key;
+			editingImageData = { ...attrs.data };
+			imageModalOpen = true;
 			return;
 		}
 		const typeDef = customTypes.find((t) => t.type === attrs._type);
@@ -278,6 +281,50 @@
 
 	let showAssetBrowser = $state(false);
 
+	// Inline image block editing — preview + alt + replace/remove. `editingImageData`
+	// holds the block's data ({ asset, alt }); alt is persisted into the node so it
+	// serializes to the portable-text block and carries visual-editing stega.
+	let imageModalOpen = $state(false);
+	let editingImageKey = $state<string | null>(null);
+	let editingImageData = $state<Record<string, any>>({});
+
+	function applyImageData(key: string, data: Record<string, any>) {
+		if (!editor) return;
+		const existing = findNodeByKey(key);
+		if (!existing) return;
+		const { tr } = editor.state;
+		tr.setNodeMarkup(existing.pos, undefined, { _type: 'image', _key: key, data });
+		editor.view.dispatch(tr);
+	}
+
+	function handleImageAltChange(alt: string) {
+		if (!editingImageKey) return;
+		editingImageData = { ...editingImageData, alt: alt || undefined };
+		applyImageData(editingImageKey, editingImageData);
+	}
+
+	function handleImageReplace() {
+		// Hand off to the asset browser, keeping editingImageKey so the alt is preserved
+		// and the modal can re-open with the new asset.
+		editingNodeKey = editingImageKey;
+		imageModalOpen = false;
+		showAssetBrowser = true;
+	}
+
+	function handleImageRemove() {
+		const key = editingImageKey;
+		imageModalOpen = false;
+		editingImageKey = null;
+		editingImageData = {};
+		if (key) handleDeleteBlock(key);
+	}
+
+	function handleImageModalClose() {
+		imageModalOpen = false;
+		editingImageKey = null;
+		editingImageData = {};
+	}
+
 	function handleInsertImageBlock() {
 		editingNodeKey = null;
 		insertMenuOpen = false;
@@ -287,13 +334,17 @@
 	function handleAssetSelected(asset: any) {
 		if (!editor || !asset) return;
 
+		const newAssetRef = { _type: 'reference', _ref: asset.id };
 		const existing = editingNodeKey ? findNodeByKey(editingNodeKey) : null;
 		if (existing) {
+			// Replace — merge into existing data so the block's alt survives the swap.
+			const prevData = (existing.node.attrs?.data as Record<string, any>) ?? {};
+			const merged = { ...prevData, asset: newAssetRef };
 			const { tr } = editor.state;
 			tr.setNodeMarkup(existing.pos, undefined, {
 				_type: 'image',
 				_key: editingNodeKey,
-				data: { asset: { _type: 'reference', _ref: asset.id } }
+				data: merged
 			});
 			editor.view.dispatch(tr);
 		} else {
@@ -305,7 +356,7 @@
 					attrs: {
 						_type: 'image',
 						_key: genKey(),
-						data: { asset: { _type: 'reference', _ref: asset.id } }
+						data: { asset: newAssetRef }
 					}
 				})
 				.run();
@@ -313,6 +364,14 @@
 
 		showAssetBrowser = false;
 		editingNodeKey = null;
+
+		// If the browser was opened from the image modal (a replace), re-open it on the
+		// updated block so the user can keep editing the alt.
+		if (editingImageKey) {
+			const updated = findNodeByKey(editingImageKey);
+			editingImageData = (updated?.node.attrs?.data as Record<string, any>) ?? {};
+			imageModalOpen = true;
+		}
 	}
 
 	function handleModalUpdate(updatedData: Record<string, any>) {
@@ -497,14 +556,18 @@
 		annotationModalOpen = true;
 	}
 
+	const editorRegistry = getRichtextEditorRegistry();
+
 	onMount(() => {
 		createEditor();
+		if (editor) editorRegistry?.set(field.name, { editor, openLinkPopover: showLinkPreview });
 		document.addEventListener('click', handleClickOutside);
 		document.addEventListener('keydown', handleKeydown);
 		element?.addEventListener('click', handleAnnotationClick);
 	});
 
 	onDestroy(() => {
+		editorRegistry?.delete(field.name);
 		editor?.destroy();
 		document.removeEventListener('click', handleClickOutside);
 		document.removeEventListener('keydown', handleKeydown);
@@ -536,6 +599,33 @@
 	// own change back" vs "parent loaded a different document."
 	let lastSyncedVersion = 0;
 	let editorJustCreated = false;
+
+	// Link marks round-trip lossy: only `href` is persisted to Portable Text, so a
+	// rehydrated link drops tiptap's presentation attrs (e.g. `class: 'richtext-link'`
+	// → null). Strip those volatile attrs before the equality check below, otherwise an
+	// identical round-trip looks "changed", replaces the doc, and collapses the caret to
+	// the end — yanking it out of a link the user just clicked in presentation mode.
+	function stripVolatileMarks(node: unknown): unknown {
+		if (Array.isArray(node)) return node.map(stripVolatileMarks);
+		if (node && typeof node === 'object') {
+			const obj = node as Record<string, unknown>;
+			const out: Record<string, unknown> = {};
+			for (const key in obj) {
+				if (key === 'marks' && Array.isArray(obj.marks)) {
+					out.marks = (obj.marks as Array<Record<string, unknown>>).map((m) =>
+						m?.type === 'link'
+							? { type: 'link', attrs: { href: (m.attrs as { href?: unknown })?.href ?? '' } }
+							: m
+					);
+				} else {
+					out[key] = stripVolatileMarks(obj[key]);
+				}
+			}
+			return out;
+		}
+		return node;
+	}
+
 	$effect(() => {
 		const v = value;
 		if (!editor) return;
@@ -547,8 +637,18 @@
 			lastSyncedVersion = internalVersion;
 			return;
 		}
-		// Replace content without polluting undo history
+		// Skip when the incoming value would produce identical content. The parent
+		// can hand us a fresh array reference with the same data (e.g. the live-
+		// preview round-trip in presentation mode reassigns documentData); replacing
+		// the doc in that case needlessly collapses the selection to the end — which
+		// reads as "the cursor jumps to the bottom" mid-edit.
 		const tiptapDoc = portableTextToTiptap(v || []);
+		if (
+			JSON.stringify(stripVolatileMarks(tiptapDoc)) ===
+			JSON.stringify(stripVolatileMarks(editor.getJSON()))
+		)
+			return;
+		// Replace content without polluting undo history
 		const newDoc = editor.state.schema.nodeFromJSON(tiptapDoc);
 		const tr = editor.state.tr.replaceWith(0, editor.state.doc.content.size, newDoc.content);
 		tr.setMeta('addToHistory', false);
@@ -589,15 +689,45 @@
 	let linkPopoverPos = $state({ top: 0, left: 0 });
 	let linkPreviewHref = $state('');
 
+	// Render the link popover at <body> level. The editor can sit inside an ancestor with a
+	// `transform` (e.g. the sliding responsive document panel), which would make the popover's
+	// `position: fixed` resolve against that ancestor instead of the viewport — placing it
+	// off-screen. Portaling escapes any such containing block / overflow clip.
+	function portal(node: HTMLElement) {
+		document.body.appendChild(node);
+		return {
+			destroy() {
+				node.remove();
+			}
+		};
+	}
+
 	function positionLinkPopover() {
-		if (!editor || !element) return;
+		if (!editor) return;
 		const { from, to } = editor.state.selection;
 		const start = editor.view.coordsAtPos(from);
 		const end = editor.view.coordsAtPos(to);
-		const editorRect = element.getBoundingClientRect();
+
+		// The popover is `position: fixed`, so it works in viewport coordinates — `coordsAtPos`
+		// already returns those. This sidesteps the editor's scroll/overflow container (e.g. the
+		// split form panel in visual-editing mode), which would otherwise clip or shift an
+		// absolutely-positioned child.
+		const POPOVER_H = 44;
+		const POPOVER_W = 320; // approx; only used to keep the popover off the right edge
+		const GAP = 4;
+		const MARGIN = 8;
+
+		// Below the selection by default; flip above when it would spill past the viewport bottom.
+		const roomBelow = end.bottom + GAP + POPOVER_H <= window.innerHeight - MARGIN;
+		const roomAbove = start.top - GAP - POPOVER_H >= MARGIN;
+		const placeBelow = roomBelow || !roomAbove;
+
 		linkPopoverPos = {
-			top: end.bottom - editorRect.top + 4,
-			left: Math.max(0, Math.min(start.left, end.left) - editorRect.left)
+			top: placeBelow ? end.bottom + GAP : start.top - GAP - POPOVER_H,
+			left: Math.min(
+				Math.max(MARGIN, Math.min(start.left, end.left)),
+				window.innerWidth - POPOVER_W - MARGIN
+			)
 		};
 	}
 
@@ -1018,7 +1148,8 @@
 
 	{#if linkMode === 'preview'}
 		<div
-			class="border-rule bg-popover absolute z-40 flex items-center gap-1.5 rounded-md border px-2 py-1.5 shadow-lg"
+			use:portal
+			class="border-rule bg-popover fixed z-[60] flex items-center gap-1.5 rounded-md border px-2 py-1.5 shadow-lg"
 			style="top: {linkPopoverPos.top}px; left: {linkPopoverPos.left}px;"
 		>
 			<a
@@ -1060,7 +1191,8 @@
 		</div>
 	{:else if linkMode === 'edit'}
 		<div
-			class="border-rule bg-popover absolute z-40 flex items-center gap-2 rounded-md border px-3 py-2 shadow-lg"
+			use:portal
+			class="border-rule bg-popover fixed z-[60] flex items-center gap-2 rounded-md border px-3 py-2 shadow-lg"
 			style="top: {linkPopoverPos.top}px; left: {linkPopoverPos.left}px;"
 		>
 			<LinkIcon class="text-muted-foreground h-4 w-4 shrink-0" />
@@ -1139,6 +1271,19 @@
 	onSelect={handleAssetSelected}
 />
 
+{#if imageModalOpen}
+	<ImageBlockModal
+		open={imageModalOpen}
+		assetRef={editingImageData?.asset?._ref}
+		alt={(editingImageData?.alt as string) ?? ''}
+		{readonly}
+		onAltChange={handleImageAltChange}
+		onReplace={handleImageReplace}
+		onRemove={handleImageRemove}
+		onClose={handleImageModalClose}
+	/>
+{/if}
+
 <style>
 	.richtext-editor {
 		position: relative;

package/dist/components/admin/fields/richtext/RichtextField.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RichtextField.svelte.d.ts","sourceRoot":"","sources":["../../../../../src/lib/components/admin/fields/richtext/RichtextField.svelte.ts"],"names":[],"mappings":"AA4BA,OAAO,EAGL,KAAK,iBAAiB,EACtB,MAAM,4BAA4B,CAAC;AAIrC,OAAO,KAAK,EAAE,UAAU,IAAI,cAAc,EAAc,MAAM,2BAA2B,CAAC;AASzF,UAAU,KAAK;IACd,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,CAAC;IAC5C,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC7C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAm+BF,QAAA,MAAM,aAAa,2CAAwC,CAAC;AAC5D,KAAK,aAAa,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AACtD,eAAe,aAAa,CAAC"}
+{"version":3,"file":"RichtextField.svelte.d.ts","sourceRoot":"","sources":["../../../../../src/lib/components/admin/fields/richtext/RichtextField.svelte.ts"],"names":[],"mappings":"AA4BA,OAAO,EAGL,KAAK,iBAAiB,EACtB,MAAM,4BAA4B,CAAC;AAIrC,OAAO,KAAK,EAAE,UAAU,IAAI,cAAc,EAAc,MAAM,2BAA2B,CAAC;AAWzF,UAAU,KAAK;IACd,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,CAAC;IAC5C,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAC7C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;IACrE,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAymCF,QAAA,MAAM,aAAa,2CAAwC,CAAC;AAC5D,KAAK,aAAa,GAAG,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;AACtD,eAAe,aAAa,CAAC"}

package/dist/components/admin/fields/richtext/svelte-node-view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"svelte-node-view.d.ts","sourceRoot":"","sources":["../../../../../src/lib/components/admin/fields/richtext/svelte-node-view.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,IAAI,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAKvE,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,KAAK,IAAI,EACvF,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,IAEvB,OAAO,qBAAqB,KAAG,mBAAmB,CA8D1D"}
+{"version":3,"file":"svelte-node-view.d.ts","sourceRoot":"","sources":["../../../../../src/lib/components/admin/fields/richtext/svelte-node-view.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,IAAI,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAKvE,wBAAgB,sBAAsB,CACrC,MAAM,EAAE,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,KAAK,IAAI,EACvF,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,IAEvB,OAAO,qBAAqB,KAAG,mBAAmB,CAyE1D"}

package/dist/components/admin/fields/richtext/svelte-node-view.js

@@ -38,7 +38,18 @@ export function SvelteNodeViewRenderer(onEdit, onDelete) {
             update(node) {
                 if (node.type.name !== 'portableTextObject')
                     return false;
+                const prevType = nodeAttrs._type;
+                const prevRef = nodeAttrs.data?.asset?._ref;
                 nodeAttrs = node.attrs;
+                const nextType = nodeAttrs._type;
+                const nextRef = nodeAttrs.data?.asset?._ref;
+                // Image views re-fetch their asset on mount, so a blind remount makes the
+                // thumbnail flash (or briefly disappear) on every keystroke/selection. Skip
+                // the remount when the image is visually unchanged — alt edits don't touch the
+                // thumbnail. Other block types still remount so their content stays in sync.
+                if (prevType === 'image' && nextType === 'image' && prevRef === nextRef) {
+                    return true;
+                }
                 unmount(currentComponent);
                 currentComponent = mountView();
                 return true;

package/dist/lib/client/index.d.ts

@@ -26,4 +26,5 @@ export type { ApiResponse } from '../api/index.js';
 export { toast } from 'svelte-sonner';
 export { confirmDialog, type ConfirmDialogOptions } from '../components/admin/confirm-dialog/confirm-dialog.svelte.js';
 export { default as ConfirmDialogHost } from '../components/admin/confirm-dialog/ConfirmDialogHost.svelte';
+export { stegaClean } from '../preview/stega.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/client/index.ts"],"names":[],"mappings":"AAIA,cAAc,gBAAgB,CAAC;AAC/B,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGlG,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAG1C,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAGjF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAG9E,OAAO,EACN,qBAAqB,EACrB,cAAc,EACd,KAAK,kBAAkB,EACvB,MAAM,+BAA+B,CAAC;AAGvC,cAAc,uBAAuB,CAAC;AAGtC,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,2CAA2C,CAAC;AACtF,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,qCAAqC,CAAC;AAGzE,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,6CAA6C,CAAC;AAG1F,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,+CAA+C,CAAC;AACvF,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,iDAAiD,CAAC;AAC3F,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,+CAA+C,CAAC;AACvF,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,gDAAgD,CAAC;AACzF,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,8CAA8C,CAAC;AACrF,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,6CAA6C,CAAC;AACnF,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,6CAA6C,CAAC;AACnF,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,8CAA8C,CAAC;AACrF,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,kDAAkD,CAAC;AAG7F,cAAc,gBAAgB,CAAC;AAE/B,cAAc,cAAc,CAAC;AAC7B,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAGtC,OAAO,EACN,aAAa,EACb,KAAK,oBAAoB,EACzB,MAAM,0DAA0D,CAAC;AAClE,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,6DAA6D,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/client/index.ts"],"names":[],"mappings":"AAIA,cAAc,gBAAgB,CAAC;AAC/B,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGlG,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAG1C,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAGjF,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAG9E,OAAO,EACN,qBAAqB,EACrB,cAAc,EACd,KAAK,kBAAkB,EACvB,MAAM,+BAA+B,CAAC;AAGvC,cAAc,uBAAuB,CAAC;AAGtC,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,2CAA2C,CAAC;AACtF,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,wCAAwC,CAAC;AAChF,OAAO,EAAE,OAAO,IAAI,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AACpE,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,qCAAqC,CAAC;AAGzE,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,6CAA6C,CAAC;AAG1F,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,+CAA+C,CAAC;AACvF,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,iDAAiD,CAAC;AAC3F,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,+CAA+C,CAAC;AACvF,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,gDAAgD,CAAC;AACzF,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,8CAA8C,CAAC;AACrF,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,6CAA6C,CAAC;AACnF,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,6CAA6C,CAAC;AACnF,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,8CAA8C,CAAC;AACrF,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,kDAAkD,CAAC;AAG7F,cAAc,gBAAgB,CAAC;AAE/B,cAAc,cAAc,CAAC;AAC7B,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAGtC,OAAO,EACN,aAAa,EACb,KAAK,oBAAoB,EACzB,MAAM,0DAA0D,CAAC;AAClE,OAAO,EAAE,OAAO,IAAI,iBAAiB,EAAE,MAAM,6DAA6D,CAAC;AAK3G,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/lib/client/index.js

@@ -38,4 +38,8 @@ export { toast } from 'svelte-sonner';
 // Confirm dialog (imperative API backed by a mounted host)
 export { confirmDialog } from '../components/admin/confirm-dialog/confirm-dialog.svelte.js';
 export { default as ConfirmDialogHost } from '../components/admin/confirm-dialog/ConfirmDialogHost.svelte';
+// Live preview — the runtime overlay + document context live in @aphexcms/visual-editing
+// (AphexVisualOverlay, getLivePreviewDocument). cms-core only owns the stega encoder used
+// by the editor and the stegaClean helper re-exported here for convenience.
+export { stegaClean } from '../preview/stega.js';
 //# sourceMappingURL=index.js.map