@eldrajs/theme-vue 0.0.0 → 0.2.0

package/dist/index.js

@@ -0,0 +1,1057 @@
+import { Fragment, computed, defineAsyncComponent, defineComponent, h, inject, nextTick, onBeforeUnmount, onMounted, onUpdated, provide, reactive, readonly, ref, shallowRef, toValue, watch, watchEffect } from "vue";
+import { EMPTY_THEME_MESSAGES, sanitizeLocaleMessages } from "@eldrajs/theme-core/i18n";
+import { DEFAULT_IMAGE_FRAMING, DEFAULT_LAYOUT_BREAKPOINTS, blockApiIdOf, buildRichTextTree, buildRichTextTree as buildRichTextTree$1, buildTemplateBlockRenames, createLayoutRenderModel, createReusableLayoutRenderModel, createTemplateLayoutRenderModel, designTokenRevisionHash, generateDesignTokenCss, hiddenLayoutBreakpoints, imageFramingAttrs, imageFramingStyle, isBlockFieldLocalized, isBlockFieldLocalized as isBlockFieldLocalized$1, layoutIdentityOf, normalizeImageFraming, normalizeThemeDesignTokens, projectEntryDataLocale, registerBlockFields, restampRichTextPositions, safeHref } from "@eldrajs/theme-core";
+import { linkTargetKeys, resolveLink, resolveLink as resolveLink$1, safeLinkHref } from "@eldrajs/theme-core/links";
+import blockImports from "virtual:eldra/blocks";
+import themeManifest from "virtual:eldra/manifest";
+import themeBreakpoints from "virtual:eldra/breakpoints";
+//#region src/context.ts
+const ELDRA_KEY = Symbol.for("eldra.themeContext");
+/**
+* The preview slice of a fresh theme context, reactive and complete. Every
+* adapter that assembles an `EldraContext` by hand — theme-nuxt's runtime
+* plugin, or an equivalent entry for another framework — must build it from
+* here: the hand-written literal had already drifted several fields behind
+* this interface, and a missing field is a runtime error rather than a type
+* error once the object is assembled elsewhere.
+*/
+function createEldraPreviewState() {
+	return reactive({
+		active: false,
+		mode: "preview",
+		locale: null,
+		sourceDrafts: {},
+		drafts: {},
+		draftSchemaApiIds: {},
+		refreshRevision: 0,
+		revision: 0,
+		designTokensRevision: 0,
+		messagesRevision: 0,
+		tokenRevision: 0,
+		editorSupportsSlots: false,
+		richTextRenderRevision: 0,
+		isRichTextRenderDeferred: void 0,
+		slotGeometryReporter: void 0
+	});
+}
+/**
+* The link slice of a fresh theme context, reactive and empty. Built here for
+* the same reason `createEldraPreviewState` is: a missing field is a runtime
+* error rather than a type error once the object is assembled elsewhere.
+*/
+/**
+* The locale slice of a context with no router behind it — a Storybook story, a unit-test mount, a
+* site whose organisation configures no locales. Every answer is the one-unprefixed-site answer,
+* so a block written against `useEldraLocale()` renders identically in all three.
+*
+* An adapter that *has* routing builds its own (see `@eldrajs/theme-nuxt`'s runtime plugin): the
+* active locale and the paths are derived from the route, which this layer knows nothing about.
+*/
+function createEldraLocaleState() {
+	return reactive({
+		active: null,
+		defaultLocale: null,
+		supported: [],
+		name: (locale) => locale,
+		path: (href) => href,
+		switchPath: () => "/",
+		select: () => {}
+	});
+}
+function createEldraLinkState() {
+	return reactive({
+		pages: [],
+		templates: [],
+		targets: /* @__PURE__ */ new Map()
+	});
+}
+function provideEldra(opts) {
+	const context = {
+		client: opts.client,
+		designTokens: reactive(normalizeThemeDesignTokens(opts.designTokens ?? { colors: {} })),
+		messages: reactive(opts.messages ?? EMPTY_THEME_MESSAGES),
+		links: createEldraLinkState(),
+		locales: createEldraLocaleState(),
+		preview: createEldraPreviewState()
+	};
+	provide(ELDRA_KEY, context);
+	return context;
+}
+function useEldra() {
+	const context = inject(ELDRA_KEY);
+	if (context === void 0) throw new Error("[eldra] useEldra() called without provideEldra() in an ancestor");
+	return context;
+}
+//#endregion
+//#region src/useEldraLink.ts
+/**
+* Resolve a `link` field's value against the site's own routes.
+*
+* Call it once per component and keep the returned function — it closes over
+* the reactive link state, so every call reads whatever the adapter has filled
+* in by then, and a row re-resolves when a target arrives or a preview draft
+* changes the value.
+*
+* Outside a themed app (a block rendered in isolation, a story with no
+* provider) it resolves nothing: every value comes back `null`, which a block
+* already has to handle for a target that no longer exists.
+*
+* Every href it hands back is spelled in the **active content locale**
+* (`useEldraLocale()`), so a navigation resolved on `/is-IS/about` points at
+* `/is-IS/products/x` and a visitor cannot be dropped back into the default
+* language by following a link. The rewrite is idempotent, which is what lets a
+* theme's router-link component prefix as well without the two compounding.
+*/
+function useEldraLink() {
+	const context = inject(ELDRA_KEY, null);
+	if (context === null || context.links === void 0) return () => null;
+	return (value) => localized(resolveLink$1(value, context.links), context.locales);
+}
+/**
+* The resolved link with every same-site href under the active locale, children included.
+*
+* Short-circuits on the two states that need no rewrite — no locale state at all, and a page in
+* the locale served at `/` — because that is nearly every page of nearly every site, and a
+* navigation block resolves one of these per row on every render.
+*/
+function localized(link, locales) {
+	if (link === null || locales === void 0) return link;
+	if (locales.active === null || locales.active === locales.defaultLocale) return link;
+	const prefix = locales.path;
+	const walk = (one) => ({
+		...one,
+		href: one.href === null ? null : prefix(one.href),
+		children: one.children.map(walk)
+	});
+	return walk(link);
+}
+//#endregion
+//#region src/useEldraLocale.ts
+/**
+* The locale this page is in, the locales the site serves, and how to spell a destination in one
+* of them.
+*
+* Call it once per component and keep what it returns — the state is reactive, so a template that
+* reads `active` or calls `path()` re-renders when the visitor changes language.
+*
+* Outside a themed app, and on a site whose organisation configures no locales, it answers the
+* one-unprefixed-site answer: `active` and `defaultLocale` `null`, `supported` empty, `path()` the
+* identity. A block can therefore read it unconditionally and render the same markup in a
+* Storybook story as on a single-locale site — which is also why a language switcher's own rule is
+* `supported.length > 1`, never "is there a locale at all".
+*/
+function useEldraLocale() {
+	return inject(ELDRA_KEY, null)?.locales ?? INERT;
+}
+/**
+* One shared inert state, not one per call: it is immutable in every way that matters (nothing
+* writes to it) and a block calling this in `setup()` must not allocate a reactive object per
+* instance.
+*/
+const INERT = createEldraLocaleState();
+//#endregion
+//#region src/EldraBlockZone.ts
+/** This theme's own id, injected at build as the manifest's `theme.id`. */
+const THEME_ID = themeManifest.theme?.id;
+/**
+* Resolve a block entry's **bare** block apiId across both supported gateway
+* response shapes. Core spells a theme's block schema `<themeId>:<apiId>` on
+* the wire; the theme's own id is stripped here (and only its own), so
+* `blockImports`, `data-eldra-schema`, the slot catalog and the overlay all
+* keep speaking the bare id `block.json` declares.
+*/
+function getBlockSchemaApiId(entry) {
+	const direct = entry.schemaApiId;
+	if (typeof direct === "string") return blockApiIdOf(direct, THEME_ID);
+	const schema = entry.schema;
+	if (typeof schema === "object" && schema !== null && typeof schema.apiId === "string") return blockApiIdOf(schema.apiId, THEME_ID);
+	return null;
+}
+const componentCache = /* @__PURE__ */ new Map();
+/** Internal renderer lookup shared by the flat and responsive layout adapters. */
+function getBlockComponent(apiId) {
+	const importer = blockImports[apiId];
+	if (importer === void 0) return null;
+	let component = componentCache.get(apiId);
+	if (component === void 0) {
+		component = defineAsyncComponent(async () => (await importer()).default);
+		componentCache.set(apiId, component);
+	}
+	return component;
+}
+const EldraBlockZone = defineComponent({
+	name: "EldraBlockZone",
+	props: { blocks: {
+		type: Array,
+		required: true
+	} },
+	setup(props) {
+		return () => props.blocks.map((entry) => {
+			const apiId = getBlockSchemaApiId(entry);
+			const component = apiId === null ? null : getBlockComponent(apiId);
+			if (apiId === null || component === null) {
+				console.warn(`[eldra] no theme block component for schemaApiId "${String(apiId)}" (entry ${entry.id})`);
+				return h("div", {
+					key: entry.id,
+					style: "display:none",
+					"data-eldra-missing-block": apiId ?? "unknown"
+				});
+			}
+			return h("div", {
+				key: entry.id,
+				"data-eldra-block": entry.id,
+				"data-eldra-schema": apiId
+			}, [h(component, { entry })]);
+		});
+	}
+});
+//#endregion
+//#region src/EldraLayout.ts
+/**
+* Marker-mode-only styling for editor slot markers. Injected as a style
+* element only while an editor with the `block-slots` capability is active;
+* static output never emits it, so public layout is unaffected. Markers
+* themselves are inert (pointer-events:none) and aria-hidden.
+*/
+const SLOT_MARKER_CSS = [
+	".eldra-slot-marker{",
+	"display:inline-block;",
+	"max-width:100%;overflow:hidden;white-space:nowrap;text-overflow:ellipsis;",
+	"font:11px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;",
+	"color:#3f3f46;background:#fafafa;",
+	"border:1px dashed #b6dfff;border-radius:3px;",
+	"padding:0 6px;margin:4px 0;",
+	"}"
+].join("");
+/**
+* Module-scope catalog of every block's declared slots, derived once from the
+* theme manifest. Keys are the same apiIds `getBlockSchemaApiId` resolves, so
+* a rendered block can look up the slot ids its author actually declared.
+*/
+function buildSlotCatalog() {
+	const blocks = themeManifest.blocks ?? [];
+	const out = {};
+	for (const block of blocks) if (block.apiId && Array.isArray(block.slots)) out[block.apiId] = block.slots;
+	return out;
+}
+const SLOT_CATALOG = buildSlotCatalog();
+function buildTemplateBlockCatalog() {
+	const blocks = themeManifest.blocks ?? [];
+	const out = {};
+	for (const block of blocks) {
+		if (typeof block.apiId !== "string" || getBlockComponent(block.apiId) === null) continue;
+		const renames = buildTemplateBlockRenames(block.migrations);
+		out[block.apiId] = {
+			apiId: block.apiId,
+			fields: (block.fields ?? []).filter((field) => typeof field.fieldId === "string").map((field) => ({
+				fieldId: field.fieldId,
+				...Object.hasOwn(field, "default") ? { default: field.default } : {}
+			})),
+			...Object.keys(renames).length === 0 ? {} : { renames }
+		};
+	}
+	return out;
+}
+const TEMPLATE_BLOCK_CATALOG = buildTemplateBlockCatalog();
+/**
+* The theme's own tablet/normal layout breakpoints, already resolved and
+* validated by Core (`resolveLayoutBreakpoints`) at build time — this
+* binding only reads it through. Carried by the separate
+* `virtual:eldra/breakpoints` module, not `virtual:eldra/manifest`: the
+* manifest is exactly what is persisted/uploaded, and Core's ingest rejects
+* an unrecognized top-level key on that file. Falls back to the defaults for
+* a build whose plugin predates this virtual module (an unresolved import
+* would throw, not silently omit the field the way an optional manifest key
+* would have).
+*/
+const MANIFEST_BREAKPOINTS$1 = themeBreakpoints ?? DEFAULT_LAYOUT_BREAKPOINTS;
+function indexEntries(entries) {
+	const indexed = /* @__PURE__ */ new Map();
+	for (const entry of entries) if (!indexed.has(entry.id)) indexed.set(entry.id, entry);
+	return indexed;
+}
+function renderIdentity(node) {
+	return node.renderId ?? node.id;
+}
+function reusablePlacement(node) {
+	if (!("placementId" in node)) return void 0;
+	return typeof node.placementId === "string" ? node.placementId : void 0;
+}
+/**
+* `data-eldra-hidden` — the breakpoints the layout hides this node at, space
+* separated, or nothing when it is visible everywhere.
+*
+* Rendered unconditionally, in preview and on the published site alike: it
+* carries no styling of its own (the generated layout CSS does the hiding), it
+* is identical on the server and on the client, and it is how the overlay finds
+* the nodes to mark when Studio switches the theme into edit mode. Deciding it
+* per bridge mode instead would be a hydration mismatch.
+*/
+function hiddenBreakpoints(style) {
+	return hiddenLayoutBreakpoints(style).join(" ") || void 0;
+}
+function renderBlock(node, entries, markerMode) {
+	const entry = entries.get(node.entryId);
+	const apiId = entry === void 0 ? null : getBlockSchemaApiId(entry);
+	const component = apiId === null ? null : getBlockComponent(apiId);
+	if (entry === void 0 || apiId === null || component === null) return h("div", {
+		key: renderIdentity(node),
+		class: node.className,
+		hidden: true,
+		"data-eldra-layout-node": node.id,
+		"data-eldra-hidden": hiddenBreakpoints(node.style),
+		"data-eldra-reusable-placement": reusablePlacement(node),
+		"data-eldra-missing-block": apiId ?? "unknown"
+	});
+	const children = [blockWithSlots(node, apiId, entries, markerMode)];
+	if (markerMode) for (const def of SLOT_CATALOG[apiId] ?? []) children.push(h("div", {
+		key: `slot-marker-${renderIdentity(node)}-${def.id}`,
+		class: "eldra-slot-marker",
+		"data-eldra-slot-marker": "",
+		"data-eldra-slot-id": def.id,
+		"data-eldra-layout-node-id": node.id,
+		"aria-hidden": "true",
+		style: "pointer-events:none"
+	}, `${def.label} · ${node.slots?.[def.id]?.length ?? 0}/${def.maxItems}`));
+	return h("div", {
+		key: renderIdentity(node),
+		class: node.className,
+		"data-eldra-layout-node": node.id,
+		"data-eldra-hidden": hiddenBreakpoints(node.style),
+		"data-eldra-reusable-placement": reusablePlacement(node),
+		"data-eldra-block": entry.id,
+		"data-eldra-schema": apiId
+	}, children);
+}
+function renderSlotChildren(host, slotId, slotChildren, entries, markerMode) {
+	const hostIdentity = renderIdentity(host);
+	return slotChildren.map((child) => {
+		const identity = [
+			hostIdentity,
+			slotId,
+			renderIdentity(child)
+		].join("\0");
+		return h("div", {
+			key: identity,
+			class: child.className,
+			"data-eldra-layout-node": child.id,
+			"data-eldra-hidden": hiddenBreakpoints(child.style),
+			"data-eldra-slot-id": slotId,
+			"data-eldra-block": child.entryId
+		}, [renderBlock(child, entries, markerMode)]);
+	});
+}
+function blockWithSlots(host, apiId, entries, markerMode) {
+	const declared = SLOT_CATALOG[apiId] ?? [];
+	const named = {};
+	for (const def of declared) {
+		const children = host.slots?.[def.id];
+		if (children === void 0 || children.length === 0) continue;
+		named[def.id] = () => renderSlotChildren(host, def.id, children, entries, markerMode);
+	}
+	const entry = entries.get(host.entryId);
+	const component = getBlockComponent(apiId);
+	return h(component, { entry }, named);
+}
+function renderNode(node, entries, markerMode) {
+	if (node.type === "template-block") {
+		const component = getBlockComponent(node.apiId);
+		if (component === null) return h("div", {
+			hidden: true,
+			"data-eldra-invalid-layout": ""
+		});
+		return h("div", {
+			key: `${node.id}\u0000${node.entry.id}`,
+			class: node.className,
+			"data-eldra-layout-node": node.id,
+			"data-eldra-template-block": node.id,
+			"data-eldra-block": node.entry.id,
+			"data-eldra-schema": node.apiId
+		}, [h(component, { entry: node.entry })]);
+	}
+	if (node.type === "block") return renderBlock(node, entries, markerMode);
+	return h("div", {
+		key: renderIdentity(node),
+		class: node.className,
+		"data-eldra-layout-node": node.id,
+		"data-eldra-hidden": hiddenBreakpoints(node.style),
+		"data-eldra-reusable-placement": reusablePlacement(node),
+		"data-eldra-layout-container": node.type
+	}, node.children.map((child) => renderNode(child, entries, markerMode)));
+}
+/**
+* Render a validated responsive layout with the same model and stylesheet used
+* by static generation. Invalid documents and unresolved entry references fail
+* closed before any customer block component is mounted.
+*/
+const EldraLayout = defineComponent({
+	name: "EldraLayout",
+	props: {
+		layout: {
+			type: null,
+			required: true
+		},
+		blocks: {
+			type: Array,
+			required: true
+		},
+		nonce: {
+			type: String,
+			required: false,
+			default: void 0
+		},
+		designTokens: {
+			type: null,
+			required: false,
+			default: void 0
+		},
+		reusableComponentProjection: {
+			type: null,
+			required: false,
+			default: void 0
+		},
+		templateEntry: {
+			type: null,
+			required: false,
+			default: void 0
+		}
+	},
+	setup(props) {
+		const context = inject(ELDRA_KEY, void 0);
+		const markerMode = computed(() => context?.preview.active === true && context?.preview.editorSupportsSlots === true);
+		const resolvedTokens = () => props.designTokens !== void 0 ? normalizeThemeDesignTokens(props.designTokens) : context?.designTokens ?? normalizeThemeDesignTokens({ colors: {} });
+		const state = computed(() => {
+			context?.preview.revision;
+			const entries = indexEntries(props.blocks.map((entry) => {
+				const draft = context?.preview.drafts[entry.id];
+				return draft === void 0 ? entry : {
+					...entry,
+					data: draft
+				};
+			}));
+			try {
+				const tokens = resolvedTokens();
+				if (props.templateEntry !== void 0) {
+					const draft = context?.preview.drafts[props.templateEntry.id];
+					const entry = draft === void 0 ? props.templateEntry : {
+						...props.templateEntry,
+						data: draft
+					};
+					return {
+						model: createTemplateLayoutRenderModel(props.layout, {
+							entry,
+							blockEntries: [...entries.values()],
+							blockCatalog: TEMPLATE_BLOCK_CATALOG,
+							allowedContainerIds: new Set(Object.keys(tokens.containers)),
+							breakpoints: MANIFEST_BREAKPOINTS$1,
+							reusableComponentProjection: props.reusableComponentProjection ?? {
+								bindings: [],
+								revisions: []
+							}
+						}),
+						entries
+					};
+				}
+				const allowedEntryIds = new Set(entries.keys());
+				const allowedContainerIds = new Set(Object.keys(tokens.containers));
+				const reusable = props.reusableComponentProjection;
+				const layoutVersion = typeof props.layout === "object" && props.layout !== null ? props.layout.version : void 0;
+				const slotContext = {
+					slotCatalog: SLOT_CATALOG,
+					entryApiId: (entryId) => {
+						const entry = entries.get(entryId);
+						return entry === void 0 ? void 0 : getBlockSchemaApiId(entry) ?? void 0;
+					}
+				};
+				return {
+					model: reusable === void 0 && layoutVersion !== 2 && layoutVersion !== 3 ? createLayoutRenderModel(props.layout, allowedEntryIds, allowedContainerIds, slotContext, MANIFEST_BREAKPOINTS$1) : createReusableLayoutRenderModel(props.layout, {
+						projection: reusable ?? {
+							bindings: [],
+							revisions: []
+						},
+						allowedEntryIds,
+						allowedContainerIds,
+						slotContext,
+						breakpoints: MANIFEST_BREAKPOINTS$1
+					}),
+					entries
+				};
+			} catch {
+				return {
+					model: null,
+					entries
+				};
+			}
+		});
+		const reportSlotMarkers = async () => {
+			if (!markerMode.value) return;
+			await nextTick();
+			const reporter = context?.preview.slotGeometryReporter;
+			if (reporter === void 0) return;
+			const elements = document.querySelectorAll("[data-eldra-slot-marker]");
+			if (elements.length === 0) return;
+			const slots = [];
+			for (const element of elements) {
+				const rect = element.getBoundingClientRect();
+				slots.push({
+					layoutNodeId: element.getAttribute("data-eldra-layout-node-id") ?? "",
+					slotId: element.getAttribute("data-eldra-slot-id") ?? "",
+					rect: {
+						x: rect.x,
+						y: rect.y,
+						width: rect.width,
+						height: rect.height
+					}
+				});
+			}
+			reporter(slots);
+		};
+		onMounted(() => {
+			reportSlotMarkers();
+		});
+		onUpdated(() => {
+			reportSlotMarkers();
+		});
+		return () => {
+			const { model, entries } = state.value;
+			if (model === null) return h("div", {
+				hidden: true,
+				"data-eldra-invalid-layout": ""
+			});
+			return h(Fragment, [
+				h("style", {
+					"data-eldra-design-token-styles": "",
+					"data-eldra-design-token-revision": designTokenRevisionHash(resolvedTokens()),
+					nonce: props.nonce
+				}, generateDesignTokenCss(resolvedTokens())),
+				h("style", {
+					"data-eldra-layout-styles": "",
+					nonce: props.nonce
+				}, model.css),
+				markerMode.value ? h("style", {
+					"data-eldra-slot-marker-styles": "",
+					nonce: props.nonce
+				}, SLOT_MARKER_CSS) : null,
+				renderNode(model.root, entries, markerMode.value)
+			]);
+		};
+	}
+});
+//#endregion
+//#region src/richTextRender.ts
+/**
+* Render a TipTap JSON document's content as Vue VNodes. Non-doc input renders
+* as an empty root.
+*
+* `generation` changes the key prefix, which makes Vue discard the subtree and
+* build it again instead of patching. §18 v3's deferred rendering needs that
+* exactly once per deferral: while a field is deferred the browser edits the
+* DOM behind Vue's back, so the vnode tree Vue is holding no longer describes
+* what is on screen, and an ordinary patch can skip a change it believes is
+* already applied. Generation 0 keeps the original keys, so nothing about the
+* ordinary render path changes.
+*/
+function renderRichTextDoc(doc, options, generation = 0) {
+	return mapChildren(buildRichTextTree$1(doc, options), generation === 0 ? "rt" : `rt${generation}`);
+}
+function mapChildren(children, key) {
+	return children.map((child, index) => typeof child === "string" ? child : mapNode(child, `${key}-${index}`));
+}
+function mapNode(node, key) {
+	if (node.children.length === 0) return h(node.tag, {
+		key,
+		...node.attrs
+	});
+	return h(node.tag, {
+		key,
+		...node.attrs
+	}, mapChildren(node.children, key));
+}
+//#endregion
+//#region src/useEldraBlockField.ts
+/**
+* Vue-facing name for theme-core's block-field lookup. The registry and the
+* `localized` resolution live in `@eldrajs/theme-core` so every framework
+* binding shares one implementation; this wrapper exists only so themes keep
+* calling a composable-shaped API.
+*
+* There is no `toolbar` here any more: §18 v3 keeps the rich-text toolbar in
+* Studio, which reads `metadata.toolbar` from Core's field definitions. The
+* vite plugin still validates the control ids at build time.
+*/
+function useEldraBlockField(apiId, fieldId) {
+	return { localized: isBlockFieldLocalized$1(apiId, fieldId) };
+}
+//#endregion
+//#region src/EldraRichText.ts
+/**
+* Renders a §18 rich-text field's TipTap JSON document. Read render only —
+* the theme SDK is a bridge, not an editor: it hosts no editing UI and
+* depends on neither TipTap nor a component library.
+*
+* §18 v3: the operator edits this render natively — theme-core's overlay
+* makes the root `contenteditable` in edit mode and reports selection, text
+* ops and commands in ProseMirror document positions; Studio owns the one
+* headless editor and the docked toolbar and echoes the document back
+* through `editor:content-update`. While Studio is editing, the root is
+* marked `data-eldra-rich-text-editing`; nothing is hidden or overlaid.
+*
+* The root carries the marking attributes the overlay's
+* `decorateStegaTextNodes`/`applyEditable`/`reconcileExternalDrafts`
+* recognize (`[data-eldra-rich-text]`) so the overlay skips per-leaf stega
+* decoration here and hands click-to-select to `theme:field-clicked`
+* instead (see theme-core's `overlay.ts`).
+*
+* Per-block toolbar: the `metadata.toolbar` data path is unchanged
+* (`block.json` → manifest → Core field metadata → Studio), but the theme no
+* longer reads it — Studio's docked toolbar does. The vite plugin's scanner
+* still validates the control ids at build time.
+*
+* Locale: an omitted `locale` prop defaults to the preview's active content
+* locale when the manifest marks the field `localized`, and to `null`
+* otherwise. That resolved locale is what `data-eldra-locale` carries, so
+* Studio edits the locale the render actually used.
+*
+* Heading outline: `minHeadingLevel` floors every heading tag at render time,
+* so one stored document fits under two different page outlines without being
+* rewritten (see that prop's own comment).
+*/
+const EldraRichText = defineComponent({
+	name: "EldraRichText",
+	props: {
+		entryId: {
+			type: String,
+			required: true
+		},
+		field: {
+			type: String,
+			required: true
+		},
+		locale: {
+			type: String,
+			required: false,
+			default: null
+		},
+		doc: {
+			type: null,
+			required: true
+		},
+		/** The owning block's schema id — a block component passes `getBlockSchemaApiId(entry)`.
+		* Used to resolve the field's `localized` flag from the block manifest. */
+		apiId: {
+			type: String,
+			required: false,
+			default: void 0
+		},
+		/**
+		* A floor for every heading in the document: a `heading` node renders as
+		* `h{max(minHeadingLevel, level)}`, still capped at 6. Defaults to 1 — the
+		* generic clamp, i.e. whatever level the document carries.
+		*
+		* A page owns its heading outline; a rich-text field does not. The same body
+		* document is legitimately an h2-and-down section in one block and an
+		* h3-and-down one in another (the starter's `article` body starts at h2, its
+		* `rich-text` block at h3), and nothing in the document or in `block.json`
+		* can say so — `metadata.toolbar`'s `heading` control id is one
+		* level-agnostic entry, so an editor can insert any level anywhere. Without
+		* this prop the only place to enforce it was a per-block transform over the
+		* TipTap JSON before handing it in (the starter shipped one); doing it here
+		* instead means the **document is never rewritten** — no copy, no
+		* reactive-state surgery, and an editor's own level survives a round trip
+		* through Studio untouched, because only the rendered tag moves.
+		*
+		* A floor, never an offset: an author who already wrote h3 under
+		* `minHeadingLevel: 3` keeps h3, and h4 stays h4 — only levels above the
+		* floor move. Every guard is in `@eldrajs/theme-core`'s own
+		* `clampHeadingLevel`, so an out-of-range or non-integer value can never
+		* produce an `<h0>`/`<h7>`.
+		*
+		* Rendering-only, deliberately: the value takes no part in position
+		* stamping (`data-eldra-pos` is the document's own numbering, which a
+		* rendered tag name cannot change), so native editing, selection reporting
+		* and `restampRichTextPositions` all behave exactly as they do without it.
+		*/
+		minHeadingLevel: {
+			type: Number,
+			required: false,
+			default: 1
+		}
+	},
+	setup(props, { expose }) {
+		const context = inject(ELDRA_KEY, null);
+		const apiId = props.apiId ?? void 0;
+		const blockField = useEldraBlockField(apiId, props.field);
+		if (apiId === void 0 && props.locale === null && context !== null) {
+			let warned = false;
+			watchEffect(() => {
+				if (warned) return;
+				if (context.preview.mode !== "edit" || context.preview.locale === null) return;
+				warned = true;
+				console.warn(`[eldra] EldraRichText: field "${props.field}" has neither an \`apiId\` nor a \`locale\` prop, so locale resolution is skipped and it reports \`locale: null\` while the preview is on "${context.preview.locale}". Pass \`api-id\` (getBlockSchemaApiId(entry)) or an explicit \`locale\`.`);
+			});
+		}
+		const locale = computed(() => props.locale ?? (blockField.localized ? context?.preview.locale ?? null : null));
+		expose({ locale });
+		/**
+		* §18 v3 deferred rendering. While the operator types natively in this
+		* root, the browser owns its DOM and theme-core says so
+		* (`isRichTextRenderDeferred`); replacing the tree would take the caret
+		* with it. So the component renders from `rendered` rather than straight
+		* from the prop, and while the field is deferred a new document only
+		* re-stamps the positions in place.
+		*
+		* Every decision here is core's: this is the predicate, the counter that
+		* makes it reactive, and the `renderKey` bump that guarantees Vue rebuilds
+		* the subtree once the field comes back — its vnode tree is stale by then,
+		* because the browser edited the DOM behind it, so an ordinary patch could
+		* skip a change it wrongly believes is already applied.
+		*/
+		const root = shallowRef(null);
+		const rendered = shallowRef(props.doc);
+		const renderKey = shallowRef(0);
+		let domOwnedByBrowser = false;
+		watch([() => props.doc, () => context?.preview.richTextRenderRevision ?? 0], () => {
+			if (context?.preview.isRichTextRenderDeferred?.({
+				entryId: props.entryId,
+				fieldPath: props.field,
+				locale: locale.value,
+				...layoutIdentityOf(root.value)
+			}) === true) {
+				domOwnedByBrowser = true;
+				if (root.value !== null && restampRichTextPositions(root.value, props.doc)) return;
+			}
+			if (domOwnedByBrowser) {
+				renderKey.value += 1;
+				domOwnedByBrowser = false;
+			}
+			rendered.value = props.doc;
+		}, { flush: "post" });
+		return () => h("div", {
+			ref: root,
+			"data-eldra-rich-text": "",
+			"data-eldra-field": props.field,
+			"data-eldra-entry": props.entryId,
+			...locale.value ? { "data-eldra-locale": locale.value } : {}
+		}, renderRichTextDoc(rendered.value, {
+			safeHref,
+			padEmptyBlocks: context?.preview.mode === "edit",
+			minHeadingLevel: props.minHeadingLevel
+		}, renderKey.value));
+	}
+});
+//#endregion
+//#region src/useEldraEntry.ts
+function useEldraEntry(opts) {
+	const context = useEldra();
+	const entry = ref(null);
+	const pending = ref(false);
+	const error = ref(null);
+	let requestVersion = 0;
+	function overlayDraft() {
+		const current = entry.value;
+		if (current === null) return;
+		const draft = context.preview.drafts[current.id];
+		if (draft !== void 0) entry.value = {
+			...current,
+			data: draft
+		};
+	}
+	async function refresh() {
+		const version = ++requestVersion;
+		pending.value = true;
+		error.value = null;
+		try {
+			const id = toValue(opts.entryId);
+			let result;
+			if (id !== void 0) result = await context.client.getEntry(opts.schemaApiId, id, opts.query);
+			else if (opts.uniqueField !== void 0) result = await context.client.getEntryByUniqueField(opts.schemaApiId, opts.uniqueField.fieldId, toValue(opts.uniqueField.value), opts.query);
+			else result = null;
+			if (version !== requestVersion) return;
+			entry.value = result;
+			overlayDraft();
+		} catch (cause) {
+			if (version !== requestVersion) return;
+			error.value = cause instanceof Error ? cause.message : String(cause);
+		} finally {
+			if (version === requestVersion) pending.value = false;
+		}
+	}
+	watch(() => [toValue(opts.entryId), opts.uniqueField === void 0 ? void 0 : toValue(opts.uniqueField.value)], () => {
+		refresh();
+	}, { immediate: true });
+	watch(() => context.preview.revision, overlayDraft);
+	return {
+		entry,
+		pending,
+		error,
+		refresh
+	};
+}
+//#endregion
+//#region src/useEldraPreview.ts
+/**
+* The theme's own tablet/normal layout breakpoints, already resolved and
+* validated by Core (`resolveLayoutBreakpoints`) at build time — included in
+* every `theme:ready` (see below) so Studio's UI can react to the theme's
+* actual ranges rather than a value it may not share. Carried by the
+* separate `virtual:eldra/breakpoints` module, not `virtual:eldra/manifest`:
+* the manifest is exactly what is persisted/uploaded, and Core's ingest
+* rejects an unrecognized top-level key on that file.
+*/
+const MANIFEST_BREAKPOINTS = themeBreakpoints ?? DEFAULT_LAYOUT_BREAKPOINTS;
+/**
+* Bounds theme:slots-rendered reports, mirroring Studio's sanitizeRenderedBlocks
+* (contracts C14): at most 500 entries, finite rect numbers, and width/height
+* within 0..100_000. The editor-side sanitizer is the authority; stay in sync.
+*/
+function sanitizeSlotGeometry(slots) {
+	if (!Array.isArray(slots)) return [];
+	const out = [];
+	for (const candidate of slots.slice(0, 500)) {
+		if (candidate === null || typeof candidate !== "object") continue;
+		const entry = candidate;
+		if (typeof entry.layoutNodeId !== "string" || entry.layoutNodeId.length > 128) continue;
+		if (typeof entry.slotId !== "string" || entry.slotId.length > 128) continue;
+		const rect = entry.rect;
+		if (rect === null || typeof rect !== "object") continue;
+		const r = rect;
+		const x = r.x;
+		const y = r.y;
+		const width = r.width;
+		const height = r.height;
+		if (typeof x !== "number" || !Number.isFinite(x)) continue;
+		if (typeof y !== "number" || !Number.isFinite(y)) continue;
+		if (typeof width !== "number" || !Number.isFinite(width) || width < 0 || width > 1e5) continue;
+		if (typeof height !== "number" || !Number.isFinite(height) || height < 0 || height > 1e5) continue;
+		out.push({
+			layoutNodeId: entry.layoutNodeId,
+			slotId: entry.slotId,
+			rect: {
+				x,
+				y,
+				width,
+				height
+			}
+		});
+	}
+	return out;
+}
+/**
+* Exported for `previewDrafts.spec.ts`: proving a draft's own top-level
+* select field unwraps the same way a select nested in an embedded block
+* does (SF-2) needs to call this directly, without standing up the whole
+* `startEldraPreview` bridge/overlay runtime that owns every other call site.
+*/
+function projectDrafts(context) {
+	for (const [entryId, draftDoc] of Object.entries(context.preview.sourceDrafts)) context.preview.drafts[entryId] = context.client.encodeEntryDataStega(entryId, projectEntryDataLocale(draftDoc, context.preview.locale, context.preview.draftSchemaApiIds[entryId]), context.preview.locale, context.preview.draftSchemaApiIds[entryId]);
+}
+function startEldraPreview(context, opts) {
+	const active = ref(false);
+	if (typeof window === "undefined" || window.parent === window) return {
+		active: readonly(active),
+		destroy: () => void 0
+	};
+	let destroyRuntime = null;
+	let disposed = false;
+	(async () => {
+		const [{ createThemeBridge }, { createOverlayRuntime, createPreviewMessageRouter }] = await Promise.all([import("@eldrajs/theme-core/bridge"), import("@eldrajs/theme-core/overlay")]);
+		if (disposed) return;
+		let overlay;
+		/** The preview token the last `editor:init` carried — see `tokenRevision`. */
+		let lastPreviewToken = null;
+		const router = createPreviewMessageRouter(() => overlay);
+		const bridge = createThemeBridge({
+			allowedOrigins: opts.allowedOrigins,
+			breakpoints: MANIFEST_BREAKPOINTS,
+			onEditorHello(capabilities) {
+				context.preview.editorSupportsSlots = router.negotiate(capabilities).slots;
+			},
+			onMessage(type, payload) {
+				if (router.route(type, payload)) return;
+				if (type === "editor:init") {
+					const init = payload;
+					context.client.enablePreview(init.previewToken);
+					if (init.previewToken !== lastPreviewToken) {
+						lastPreviewToken = init.previewToken;
+						context.preview.tokenRevision += 1;
+					}
+					context.preview.active = true;
+					context.preview.mode = init.mode;
+					context.preview.locale = init.locale;
+					projectDrafts(context);
+					active.value = true;
+					overlay.setMode(init.mode);
+					overlay.start();
+					context.preview.refreshRevision += 1;
+					context.preview.revision += 1;
+					if (init.path !== window.location.pathname) opts.onNavigate?.(init.path);
+				} else if (type === "editor:content-update") {
+					const entries = payload.entries;
+					overlay.acceptExternalUpdate(entries.map(({ entryId }) => entryId));
+					for (const update of entries) {
+						context.preview.sourceDrafts[update.entryId] = update.draftDoc;
+						context.preview.draftSchemaApiIds[update.entryId] = blockApiIdOf(update.schemaApiId, themeManifest.theme?.id);
+					}
+					projectDrafts(context);
+					context.preview.refreshRevision += 1;
+					context.preview.revision += 1;
+					queueMicrotask(() => {
+						overlay.rescan();
+						overlay.reconcileExternalDrafts(context.preview.drafts, entries.map(({ entryId }) => entryId));
+					});
+				} else if (type === "editor:design-tokens") applyResolvedDesignTokens(context, payload);
+				else if (type === "editor:theme-messages") applyThemeMessages(context, payload);
+				else if (type === "editor:set-mode") {
+					const mode = payload.mode;
+					context.preview.mode = mode;
+					overlay.setMode(mode);
+				} else if (type === "editor:navigate") opts.onNavigate?.(payload.path);
+				else if (type === "editor:refresh") context.preview.refreshRevision += 1;
+			}
+		});
+		overlay = createOverlayRuntime({
+			post: (type, payload) => bridge.post(type, payload),
+			breakpoints: MANIFEST_BREAKPOINTS
+		});
+		context.preview.slotGeometryReporter = (slots) => {
+			const safe = sanitizeSlotGeometry(slots);
+			if (safe.length === 0) return;
+			bridge.post("theme:slots-rendered", { slots: safe });
+		};
+		context.preview.isRichTextRenderDeferred = (identity) => overlay.isRichTextRenderDeferred(identity);
+		const stopRichTextRenderState = overlay.onRichTextRenderState(() => {
+			context.preview.richTextRenderRevision += 1;
+		});
+		const stopRequestErrors = context.client.onRequestError?.((error) => {
+			if (!context.client.previewEnabled || error.status === 404) return;
+			bridge.post("theme:request-failed", {
+				status: error.status,
+				path: error.path.slice(0, 256)
+			});
+		}) ?? (() => void 0);
+		destroyRuntime = () => {
+			context.client.disablePreview();
+			context.preview.active = false;
+			context.preview.editorSupportsSlots = false;
+			context.preview.slotGeometryReporter = void 0;
+			stopRichTextRenderState();
+			stopRequestErrors();
+			context.preview.isRichTextRenderDeferred = void 0;
+			active.value = false;
+			router.reset();
+			overlay.stop();
+			bridge.destroy();
+			document.querySelector("style[data-eldra-live-design-token-styles]")?.remove();
+		};
+	})();
+	return {
+		active: readonly(active),
+		destroy: () => {
+			disposed = true;
+			destroyRuntime?.();
+		}
+	};
+}
+function boundedPayload(value) {
+	try {
+		return new TextEncoder().encode(JSON.stringify(value)).byteLength <= 65536;
+	} catch {
+		return false;
+	}
+}
+function replaceRecord(target, source) {
+	for (const key of Object.keys(target)) delete target[key];
+	for (const key of Object.keys(source).sort((a, b) => a.localeCompare(b))) target[key] = source[key];
+}
+const staticDesignTokenIds = /* @__PURE__ */ new WeakMap();
+function getStaticDesignTokenIds(context) {
+	const existing = staticDesignTokenIds.get(context);
+	if (existing !== void 0) return existing;
+	const captured = {
+		colors: Object.keys(context.designTokens.colors),
+		containers: Object.keys(context.designTokens.containers)
+	};
+	staticDesignTokenIds.set(context, captured);
+	return captured;
+}
+function applyResolvedDesignTokens(context, update) {
+	if (!boundedPayload(update)) return false;
+	try {
+		const resolved = normalizeThemeDesignTokens(update.resolved);
+		if (!Number.isSafeInteger(update.revision) || update.revision <= context.preview.designTokensRevision) return false;
+		const staticIds = getStaticDesignTokenIds(context);
+		const removedColors = staticIds.colors.filter((id) => resolved.colors[id] === void 0);
+		const removedContainers = staticIds.containers.filter((id) => resolved.containers[id] === void 0);
+		replaceRecord(context.designTokens.colors, resolved.colors);
+		replaceRecord(context.designTokens.containers, resolved.containers);
+		if (resolved.allowCustomColors === true) context.designTokens.allowCustomColors = true;
+		else delete context.designTokens.allowCustomColors;
+		context.preview.designTokensRevision = update.revision;
+		if (typeof document !== "undefined") syncDesignTokenStyle(context, {
+			colors: removedColors,
+			containers: removedContainers
+		});
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Applies an `editor:theme-messages` push from Studio's "Theme texts" page: for every locale tag
+* the payload names, **replaces** `context.messages.locales[tag]` wholesale with the payload's own
+* record (sanitized through `@eldrajs/theme-core/i18n`'s `sanitizeLocaleMessages` — non-string
+* values dropped, and a forbidden tag, `__proto__`/`prototype`/`constructor`, skipped entirely
+* rather than written through: `context.messages` is `reactive(...)`, so an assignment to that
+* literal key on its `locales` object would reassign the live, shared object's own prototype
+* instead of adding a property named for it) — never a per-key merge, since Studio always sends a
+* locale's full resolved set, the same shape `virtual:eldra/messages` serves. A locale the payload
+* does not mention is left untouched.
+*
+* `revision` guards the same way `designTokensRevision` does: a push whose revision is not
+* strictly greater than the last one applied is ignored, so an out-of-order delivery (a Studio
+* reconnect replaying its last push, say) cannot roll a live edit backwards.
+*/
+function applyThemeMessages(context, update) {
+	if (!boundedPayload(update)) return false;
+	if (!Number.isSafeInteger(update.revision) || update.revision <= context.preview.messagesRevision) return false;
+	if (typeof update.locales !== "object" || update.locales === null) return false;
+	for (const tag of Object.keys(update.locales).sort((a, b) => a.localeCompare(b))) {
+		const record = update.locales[tag];
+		if (typeof record !== "object" || record === null) continue;
+		const sanitized = sanitizeLocaleMessages(tag, record);
+		if (sanitized === null) continue;
+		context.messages.locales[tag] = sanitized;
+	}
+	context.preview.messagesRevision = update.revision;
+	return true;
+}
+function syncDesignTokenStyle(context, removed) {
+	let style = document.querySelector("style[data-eldra-live-design-token-styles]");
+	if (style === null) {
+		style = document.createElement("style");
+		style.dataset.eldraLiveDesignTokenStyles = "";
+		const nonce = document.querySelector("style[data-eldra-layout-styles][nonce]")?.nonce;
+		if (nonce) style.nonce = nonce;
+		document.head.append(style);
+	}
+	const removedDeclarations = [...removed.colors.sort((a, b) => a.localeCompare(b)).flatMap((id) => [`--eldra-color-${id}:initial;`, `--color-${id}:initial;`]), ...removed.containers.sort((a, b) => a.localeCompare(b)).flatMap((id) => [
+		`--eldra-container-${id}-max-width:initial;`,
+		`--eldra-container-${id}-gutter-normal:initial;`,
+		`--eldra-container-${id}-gutter-tablet:initial;`,
+		`--eldra-container-${id}-gutter-mobile:initial;`
+	])].join("");
+	const tombstones = removedDeclarations === "" ? "" : `:root{${removedDeclarations}}`;
+	style.textContent = `${tombstones}${generateDesignTokenCss(context.designTokens)}`;
+	style.dataset.eldraDesignTokenRevision = String(context.preview.designTokensRevision);
+}
+function useEldraPreview(opts) {
+	const active = ref(false);
+	if (typeof window === "undefined" || window.parent === window) return { active: readonly(active) };
+	const runtime = startEldraPreview(useEldra(), opts);
+	onBeforeUnmount(() => {
+		runtime.destroy();
+	});
+	return { active: runtime.active };
+}
+//#endregion
+export { DEFAULT_IMAGE_FRAMING, ELDRA_KEY, EldraBlockZone, EldraLayout, EldraRichText, buildRichTextTree, createEldraLinkState, createEldraLocaleState, createEldraPreviewState, getBlockSchemaApiId, imageFramingAttrs, imageFramingStyle, isBlockFieldLocalized, linkTargetKeys, normalizeImageFraming, provideEldra, registerBlockFields, renderRichTextDoc, resolveLink, safeLinkHref, startEldraPreview, useEldra, useEldraBlockField, useEldraEntry, useEldraLink, useEldraLocale, useEldraPreview };