@getdom/studio 0.1.0

package/src/pages/lib/headless/transitions.d.ts

@@ -0,0 +1,5 @@
+/* eslint-disable */
+// Generated by scripts/generate-types.mjs. Do not edit by hand.
+export declare function hasCustomTransitions(host: HTMLElement): boolean;
+export declare function runEnter(host: HTMLElement, el: HTMLElement, options?: { signal?: AbortSignal }): Promise<void>;
+export declare function runLeave(host: HTMLElement, el: HTMLElement, options?: { signal?: AbortSignal }): Promise<void>;

package/src/pages/lib/headless/transitions.js

@@ -0,0 +1,89 @@
+// Headless UI-style enter/leave class transitions.
+// Reads `enter`, `enter-from`, `enter-to`, `leave`, `leave-from`, `leave-to`
+// attributes from a host element and applies the class strings to `el`.
+
+const ENTER_KEYS = ['enter', 'enter-from', 'enter-to'];
+const LEAVE_KEYS = ['leave', 'leave-from', 'leave-to'];
+
+export function hasCustomTransitions(host) {
+	return ENTER_KEYS.some((k) => host.hasAttribute(k))
+		|| LEAVE_KEYS.some((k) => host.hasAttribute(k));
+}
+
+function splitClasses(value) {
+	return (value ?? '').trim().split(/\s+/).filter(Boolean);
+}
+
+function durationMs(classLists) {
+	const text = classLists.flat().join(' ');
+	let ms = 0;
+	const bracket = text.match(/duration-\[(\d+(?:\.\d+)?)(ms|s)?\]/);
+	if (bracket) {
+		const n = parseFloat(bracket[1]);
+		ms = Math.max(ms, bracket[2] === 's' ? n * 1000 : n);
+	}
+	for (const m of text.matchAll(/\bduration-(\d+)\b/g)) {
+		ms = Math.max(ms, Number(m[1]));
+	}
+	return ms || 200;
+}
+
+function nextFrame() {
+	return new Promise((resolve) => {
+		requestAnimationFrame(() => requestAnimationFrame(resolve));
+	});
+}
+
+function waitForTransition(classLists, signal) {
+	return new Promise((resolve) => {
+		let settled = false;
+		const done = () => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			signal?.removeEventListener('abort', done);
+			resolve();
+		};
+		const timer = setTimeout(done, durationMs(classLists) + 50);
+		signal?.addEventListener('abort', done, { once: true });
+	});
+}
+
+function setClasses(el, add, remove) {
+	if (remove.length) el.classList.remove(...remove);
+	if (add.length) el.classList.add(...add);
+}
+
+function forceStyleFlush(el) {
+	el.getBoundingClientRect();
+}
+
+export async function runEnter(host, el, { signal } = {}) {
+	const enter = splitClasses(host.getAttribute('enter'));
+	const from = splitClasses(host.getAttribute('enter-from'));
+	const to = splitClasses(host.getAttribute('enter-to'));
+	if (!enter.length && !from.length && !to.length) return;
+
+	setClasses(el, [...enter, ...from], []);
+	forceStyleFlush(el);
+	await nextFrame();
+	if (signal?.aborted) return;
+	setClasses(el, to, from);
+	await waitForTransition([enter, from, to], signal);
+	setClasses(el, [], [...enter, ...to]);
+}
+
+export async function runLeave(host, el, { signal } = {}) {
+	const leave = splitClasses(host.getAttribute('leave'));
+	const from = splitClasses(host.getAttribute('leave-from'));
+	const to = splitClasses(host.getAttribute('leave-to'));
+	if (!leave.length && !from.length && !to.length) return;
+
+	setClasses(el, [...leave, ...from], []);
+	forceStyleFlush(el);
+	await nextFrame();
+	if (signal?.aborted) return;
+	setClasses(el, to, from);
+	await waitForTransition([leave, from, to], signal);
+	setClasses(el, [], [...leave, ...to]);
+}

package/src/pages/lib/vue/_internal/DomLiquidGlassSurface.vue

@@ -0,0 +1,310 @@
+<script setup>
+import {
+	onBeforeUnmount,
+	onMounted,
+	ref,
+	useId,
+} from 'vue';
+import {
+	buildLiquidGlassMap,
+	supportsLiquidGlassRefraction,
+} from './liquidGlass.js';
+
+defineOptions({
+	name: 'DomLiquidGlassSurface',
+	__doc: {
+		description: 'An experimental standalone surface that refracts content behind it with a safe translucent fallback.',
+	},
+});
+
+const MAP_UPDATE_DELAY = 140;
+const FALLBACK_FILTER = 'blur(var(--dom-liquid-glass-fallback-blur, 18px)) saturate(var(--dom-liquid-glass-fallback-saturation, 1.2))';
+
+defineProps({
+	refraction: {
+		type: Number,
+		default: 50,
+	},
+});
+
+const surface = ref(null);
+const mapHref = ref('');
+const mode = ref('fallback');
+const filterValue = ref(FALLBACK_FILTER);
+const filterId = `dom-liquid-glass-${useId().replace(/[^a-zA-Z0-9_-]/g, '')}`;
+
+let mapUpdateTimer = null;
+let resizeObserver = null;
+
+/**
+ * Rasterize a displacement map that matches the current surface geometry.
+ *
+ * @returns {void}
+ */
+function updateGlassMap() {
+	if (!surface.value || mode.value !== 'enhanced') return;
+
+	const bounds = surface.value.getBoundingClientRect();
+	const styles = window.getComputedStyle(surface.value);
+	const radius = Number.parseFloat(styles.borderTopLeftRadius) || 0;
+
+	mapHref.value = buildLiquidGlassMap({
+		width: bounds.width,
+		height: bounds.height,
+		radius,
+	});
+}
+
+/**
+ * Debounce displacement-map generation while the surface is resizing.
+ *
+ * @returns {void}
+ */
+function queueGlassMapUpdate() {
+	if (mapUpdateTimer !== null) window.clearTimeout(mapUpdateTimer);
+	mapUpdateTimer = window.setTimeout(updateGlassMap, MAP_UPDATE_DELAY);
+}
+
+/**
+ * Enable the enhanced filter when the current rendering engine supports it.
+ *
+ * @returns {void}
+ */
+function activateLiquidGlass() {
+	if (!supportsLiquidGlassRefraction()) return;
+
+	mode.value = 'enhanced';
+	filterValue.value = `url("#${filterId}") blur(var(--dom-liquid-glass-blur, 7px)) saturate(var(--dom-liquid-glass-saturation, 1.4))`;
+	updateGlassMap();
+
+	if (typeof ResizeObserver === 'function') {
+		resizeObserver = new ResizeObserver(queueGlassMapUpdate);
+		resizeObserver.observe(surface.value);
+	}
+
+	window.addEventListener('resize', queueGlassMapUpdate, { passive: true });
+}
+
+/**
+ * Release observers and pending work owned by this surface instance.
+ *
+ * @returns {void}
+ */
+function disposeLiquidGlass() {
+	resizeObserver?.disconnect();
+	resizeObserver = null;
+	window.removeEventListener('resize', queueGlassMapUpdate);
+
+	if (mapUpdateTimer !== null) {
+		window.clearTimeout(mapUpdateTimer);
+		mapUpdateTimer = null;
+	}
+}
+
+onMounted(activateLiquidGlass);
+onBeforeUnmount(disposeLiquidGlass);
+</script>
+
+<template>
+	<div
+		ref="surface"
+		class="surface"
+		:data-liquid-glass-mode="mode"
+		:style="{ '--dom-liquid-glass-filter': filterValue }"
+	>
+		<div class="content">
+			<slot />
+		</div>
+
+		<svg
+			class="defs"
+			aria-hidden="true"
+			focusable="false"
+			width="0"
+			height="0"
+		>
+			<defs>
+				<filter
+					:id="filterId"
+					color-interpolation-filters="sRGB"
+					x="-25%"
+					y="-25%"
+					width="150%"
+					height="150%"
+				>
+					<feImage
+						x="0"
+						y="0"
+						width="100%"
+						height="100%"
+						preserveAspectRatio="none"
+						:href="mapHref || undefined"
+						:xlink:href="mapHref || undefined"
+						result="map"
+					/>
+					<feDisplacementMap
+						in="SourceGraphic"
+						in2="map"
+						xChannelSelector="R"
+						yChannelSelector="B"
+						:scale="-refraction"
+						result="displaced-red"
+					/>
+					<feColorMatrix
+						in="displaced-red"
+						type="matrix"
+						values="1 0 0 0 0  0 0 0 0 0  0 0 0 0 0  0 0 0 1 0"
+						result="red"
+					/>
+					<feDisplacementMap
+						in="SourceGraphic"
+						in2="map"
+						xChannelSelector="R"
+						yChannelSelector="B"
+						:scale="-Math.max(0, refraction - 3)"
+						result="displaced-green"
+					/>
+					<feColorMatrix
+						in="displaced-green"
+						type="matrix"
+						values="0 0 0 0 0  0 1 0 0 0  0 0 0 0 0  0 0 0 1 0"
+						result="green"
+					/>
+					<feDisplacementMap
+						in="SourceGraphic"
+						in2="map"
+						xChannelSelector="R"
+						yChannelSelector="B"
+						:scale="-Math.max(0, refraction - 6)"
+						result="displaced-blue"
+					/>
+					<feColorMatrix
+						in="displaced-blue"
+						type="matrix"
+						values="0 0 0 0 0  0 0 0 0 0  0 0 1 0 0  0 0 0 1 0"
+						result="blue"
+					/>
+					<feBlend in="red" in2="green" mode="screen" result="red-green" />
+					<feBlend in="red-green" in2="blue" mode="screen" result="output" />
+					<feGaussianBlur in="output" stdDeviation="0.7" />
+				</filter>
+			</defs>
+		</svg>
+	</div>
+</template>
+
+<style scoped>
+.surface {
+	--dom-liquid-glass-default-surface-fill: var(
+		--dom-liquid-glass-fallback-background,
+		color-mix(in oklch, var(--canvas, white) 68%, transparent)
+	);
+	--dom-liquid-glass-default-edge-top: rgb(255 255 255 / 0.58);
+	--dom-liquid-glass-default-edge-top: light-dark(rgb(255 255 255 / 0.58), rgb(255 255 255 / 0.24));
+	--dom-liquid-glass-default-edge-upper: rgb(255 255 255 / 0.28);
+	--dom-liquid-glass-default-edge-upper: light-dark(rgb(255 255 255 / 0.28), rgb(255 255 255 / 0.11));
+	--dom-liquid-glass-default-edge-side: rgb(255 255 255 / 0.14);
+	--dom-liquid-glass-default-edge-side: light-dark(rgb(255 255 255 / 0.14), rgb(255 255 255 / 0.05));
+	--dom-liquid-glass-default-edge-bottom: rgb(255 255 255 / 0.09);
+	--dom-liquid-glass-default-edge-bottom: light-dark(rgb(255 255 255 / 0.09), rgb(255 255 255 / 0.03));
+	--dom-liquid-glass-default-shadow:
+		0 1px 2px rgb(15 23 42 / 0.1),
+		0 8px 24px -8px rgb(15 23 42 / 0.2),
+		0 22px 52px -18px rgb(15 23 42 / 0.24);
+	--dom-liquid-glass-default-shadow:
+		0 1px 2px light-dark(rgb(15 23 42 / 0.1), rgb(0 0 0 / 0.42)),
+		0 8px 24px -8px light-dark(rgb(15 23 42 / 0.2), rgb(0 0 0 / 0.58)),
+		0 22px 52px -18px light-dark(rgb(15 23 42 / 0.24), rgb(0 0 0 / 0.72));
+	--dom-liquid-glass-default-inner-edge-top: rgb(255 255 255 / 0.42);
+	--dom-liquid-glass-default-inner-edge-top: light-dark(rgb(255 255 255 / 0.42), rgb(255 255 255 / 0.18));
+	--dom-liquid-glass-default-inner-edge-glow: rgb(255 255 255 / 0.09);
+	--dom-liquid-glass-default-inner-edge-glow: light-dark(rgb(255 255 255 / 0.09), rgb(255 255 255 / 0.035));
+	--dom-liquid-glass-default-inner-edge-side: rgb(255 255 255 / 0.08);
+	--dom-liquid-glass-default-inner-edge-side: light-dark(rgb(255 255 255 / 0.08), rgb(255 255 255 / 0.03));
+	--dom-liquid-glass-default-inner-edge-bottom: rgb(15 23 42 / 0.08);
+	--dom-liquid-glass-default-inner-edge-bottom: light-dark(rgb(15 23 42 / 0.08), rgb(0 0 0 / 0.34));
+
+	position: var(--dom-liquid-glass-position, relative);
+	isolation: isolate;
+	overflow: hidden;
+	color: var(--canvas-fg, #171717);
+	background:
+		linear-gradient(
+			var(--dom-liquid-glass-surface-fill, var(--dom-liquid-glass-default-surface-fill)),
+			var(--dom-liquid-glass-surface-fill, var(--dom-liquid-glass-default-surface-fill))
+		) padding-box,
+		linear-gradient(
+			180deg,
+			var(--dom-liquid-glass-edge-top, var(--dom-liquid-glass-default-edge-top)) 0%,
+			var(--dom-liquid-glass-edge-upper, var(--dom-liquid-glass-default-edge-upper)) 20%,
+			var(--dom-liquid-glass-edge-side, var(--dom-liquid-glass-default-edge-side)) 58%,
+			var(--dom-liquid-glass-edge-bottom, var(--dom-liquid-glass-default-edge-bottom)) 100%
+		) border-box;
+	border: 1px solid transparent;
+	border-radius: var(--dom-liquid-glass-radius, var(--radius-lg, 1.25rem));
+	box-shadow: var(
+		--dom-liquid-glass-shadow,
+		var(--dom-liquid-glass-default-shadow)
+	);
+	-webkit-backdrop-filter: var(--dom-liquid-glass-filter);
+	backdrop-filter: var(--dom-liquid-glass-filter);
+}
+
+.surface[data-liquid-glass-mode='enhanced'] {
+	--dom-liquid-glass-default-surface-fill: var(
+		--dom-liquid-glass-background,
+		color-mix(in oklch, var(--canvas, white) 40%, transparent)
+	);
+}
+
+.surface::before,
+.surface::after {
+	position: absolute;
+	inset: 0;
+	pointer-events: none;
+	content: '';
+	border-radius: inherit;
+}
+
+.surface::before {
+	z-index: 1;
+	box-shadow:
+		inset 0 1px 0 var(--dom-liquid-glass-inner-edge-top, var(--dom-liquid-glass-default-inner-edge-top)),
+		inset 0 3px 8px var(--dom-liquid-glass-inner-edge-glow, var(--dom-liquid-glass-default-inner-edge-glow)),
+		inset 1px 0 0 var(--dom-liquid-glass-inner-edge-side, var(--dom-liquid-glass-default-inner-edge-side)),
+		inset -1px 0 0 var(--dom-liquid-glass-inner-edge-side, var(--dom-liquid-glass-default-inner-edge-side)),
+		inset 0 -1px 0 var(--dom-liquid-glass-inner-edge-bottom, var(--dom-liquid-glass-default-inner-edge-bottom));
+}
+
+.surface::after {
+	z-index: 0;
+	background: linear-gradient(
+		155deg,
+		rgb(255 255 255 / 0.14),
+		transparent 34%,
+		rgb(255 255 255 / 0.04) 72%,
+		rgb(255 255 255 / 0.08)
+	);
+}
+
+.content {
+	position: relative;
+	z-index: 2;
+}
+
+.defs {
+	position: absolute;
+	width: 0;
+	height: 0;
+	overflow: hidden;
+}
+
+@media (prefers-reduced-transparency: reduce) {
+	.surface {
+		background: var(--canvas, white);
+		border-color: var(--border, rgb(0 0 0 / 0.14));
+		-webkit-backdrop-filter: none;
+		backdrop-filter: none;
+	}
+}
+</style>

package/src/pages/lib/vue/_internal/liquidGlass.js

@@ -0,0 +1,112 @@
+const DEFAULT_BORDER_RATIO = 0.07;
+const DEFAULT_LIGHTNESS = 50;
+const DEFAULT_ALPHA = 0.93;
+const DEFAULT_EDGE_BLUR = 11;
+
+/**
+ * Clamp a numeric value to a finite range.
+ *
+ * @param {number} value Value to clamp.
+ * @param {number} min Minimum accepted value.
+ * @param {number} max Maximum accepted value.
+ * @returns {number} Clamped finite value.
+ */
+function clamp(value, min, max) {
+	return Math.min(max, Math.max(min, Number.isFinite(value) ? value : min));
+}
+
+/**
+ * Normalize an observed CSS dimension for safe SVG interpolation.
+ *
+ * @param {number} value Observed element dimension in CSS pixels.
+ * @returns {number} Positive whole-pixel dimension.
+ */
+function normalizeDimension(value) {
+	return Math.max(1, Math.round(Number(value) || 0));
+}
+
+/**
+ * Determine whether the current engine can render SVG displacement filters as
+ * backdrop filters. WebKit accepts the syntax but currently does not render
+ * the SVG filter, so it must remain on the CSS-only fallback.
+ *
+ * @returns {boolean} True when enhanced backdrop refraction should be enabled.
+ */
+export function supportsLiquidGlassRefraction() {
+	if (typeof window === 'undefined' || typeof CSS === 'undefined') return false;
+	if (window.matchMedia?.('(prefers-reduced-transparency: reduce)').matches) return false;
+
+	const filter = 'url("#dom-liquid-glass-probe") blur(1px)';
+	const supportsSyntax = CSS.supports('backdrop-filter', filter)
+		|| CSS.supports('-webkit-backdrop-filter', filter);
+	if (!supportsSyntax) return false;
+
+	const userAgent = window.navigator?.userAgent || '';
+	const usesWebKit = /AppleWebKit/i.test(userAgent)
+		&& !/(Chrome|Chromium|Edg|OPR|SamsungBrowser)/i.test(userAgent);
+
+	return !usesWebKit;
+}
+
+/**
+ * Build a pill or rounded-rectangle displacement map for one glass surface.
+ * Red encodes horizontal displacement, blue encodes vertical displacement,
+ * and the blurred neutral interior keeps the centre comparatively stable.
+ *
+ * @param {object} options Map generation options.
+ * @param {number} options.width Surface width in CSS pixels.
+ * @param {number} options.height Surface height in CSS pixels.
+ * @param {number} [options.radius] Uniform surface radius in CSS pixels.
+ * @param {number} [options.borderRatio] Proportion of the shortest edge used for the refractive rim.
+ * @param {number} [options.lightness] Neutral interior lightness percentage.
+ * @param {number} [options.alpha] Neutral interior opacity.
+ * @param {number} [options.edgeBlur] Blur applied to the neutral interior edge.
+ * @returns {string} Encoded SVG data URI suitable for an SVG feImage href.
+ */
+export function buildLiquidGlassMap({
+	width,
+	height,
+	radius,
+	borderRatio = DEFAULT_BORDER_RATIO,
+	lightness = DEFAULT_LIGHTNESS,
+	alpha = DEFAULT_ALPHA,
+	edgeBlur = DEFAULT_EDGE_BLUR,
+}) {
+	const resolvedWidth = normalizeDimension(width);
+	const resolvedHeight = normalizeDimension(height);
+	const shortestEdge = Math.min(resolvedWidth, resolvedHeight);
+	const requestedRadius = Number(radius);
+	const resolvedRadius = clamp(
+		Number.isFinite(requestedRadius) ? requestedRadius : shortestEdge / 2,
+		0,
+		shortestEdge / 2,
+	);
+	const resolvedBorderRatio = clamp(Number(borderRatio), 0, 0.5);
+	const resolvedLightness = clamp(Number(lightness), 0, 100);
+	const resolvedAlpha = clamp(Number(alpha), 0, 1);
+	const resolvedEdgeBlur = clamp(Number(edgeBlur), 0, shortestEdge / 2);
+	const inset = shortestEdge * resolvedBorderRatio;
+	const innerWidth = Math.max(1, resolvedWidth - (inset * 2));
+	const innerHeight = Math.max(1, resolvedHeight - (inset * 2));
+	const innerRadius = Math.max(0, resolvedRadius - inset);
+	const svg = [
+		`<svg viewBox="0 0 ${resolvedWidth} ${resolvedHeight}" xmlns="http://www.w3.org/2000/svg">`,
+		'<defs>',
+		'<linearGradient id="red" x1="100%" y1="0%" x2="0%" y2="0%">',
+		'<stop offset="0%" stop-color="#000"/>',
+		'<stop offset="100%" stop-color="red"/>',
+		'</linearGradient>',
+		'<linearGradient id="blue" x1="0%" y1="0%" x2="0%" y2="100%">',
+		'<stop offset="0%" stop-color="#000"/>',
+		'<stop offset="100%" stop-color="blue"/>',
+		'</linearGradient>',
+		'</defs>',
+		`<rect width="${resolvedWidth}" height="${resolvedHeight}" fill="black"/>`,
+		`<rect width="${resolvedWidth}" height="${resolvedHeight}" rx="${resolvedRadius}" fill="url(#red)"/>`,
+		`<rect width="${resolvedWidth}" height="${resolvedHeight}" rx="${resolvedRadius}" fill="url(#blue)" style="mix-blend-mode:difference"/>`,
+		`<rect x="${inset}" y="${inset}" width="${innerWidth}" height="${innerHeight}" rx="${innerRadius}" fill="hsl(0 0% ${resolvedLightness}% / ${resolvedAlpha})" style="filter:blur(${resolvedEdgeBlur}px)"/>`,
+		'</svg>',
+	].join('');
+
+	return `data:image/svg+xml,${encodeURIComponent(svg)}`;
+}

package/src/pages/lib/vue/_internal/liquidGlassConfig.js

@@ -0,0 +1,10 @@
+/**
+ * Private feature switches for the promoted liquid-glass treatments.
+ *
+ * Set either value to false to restore the preceding surface treatment
+ * without changing component call sites or public package APIs.
+ */
+export const LIQUID_GLASS_EFFECTS = Object.freeze({
+	commandPalette: false,
+	stickyHeader: true,
+});

package/src/pages/lib/vue/codeHighlighter.js

@@ -0,0 +1,132 @@
+// Optional syntax highlighting via Shiki, loaded from an ESM CDN at runtime.
+//
+// Shiki is polish, not a hard runtime dependency. If the CDN is blocked,
+// unavailable, or the app is rendering on the server, callers get null and
+// can fall back to plain code rendering.
+
+const SHIKI_URL = 'https://esm.sh/shiki@1';
+const LIGHT = 'light-plus';
+const DARK = 'dark-plus';
+const LANGS = ['vue', 'html', 'javascript', 'typescript', 'css', 'json', 'markdown', 'python', 'bash', 'sql', 'text'];
+const LANG_ALIASES = {
+	js: 'javascript',
+	ts: 'typescript',
+	md: 'markdown',
+	sh: 'bash',
+	txt: 'text',
+};
+
+export const CODE_LANGUAGE_OPTIONS = [
+	{ label: 'Plain text', value: 'txt' },
+	{ label: 'Vue', value: 'vue' },
+	{ label: 'HTML', value: 'html' },
+	{ label: 'JavaScript', value: 'js' },
+	{ label: 'TypeScript', value: 'ts' },
+	{ label: 'CSS', value: 'css' },
+	{ label: 'JSON', value: 'json' },
+	{ label: 'Markdown', value: 'md' },
+	{ label: 'Python', value: 'python' },
+	{ label: 'Bash', value: 'bash' },
+	{ label: 'SQL', value: 'sql' },
+];
+
+let highlighterPromise = null;
+let loadFailed = false;
+const languagePromises = new Map();
+
+/**
+ * Loads the shared Shiki highlighter when the browser can reach the CDN.
+ *
+ * @returns {Promise<object|null>} Shiki highlighter instance, or null when unavailable.
+ */
+async function getHighlighter() {
+	if (loadFailed) return null;
+	if (highlighterPromise) return highlighterPromise;
+
+	highlighterPromise = (async () => {
+		if (typeof window === 'undefined') return null;
+		try {
+			const shiki = await import(/* @vite-ignore */ SHIKI_URL);
+			const factory = shiki.createHighlighter || shiki.getHighlighter;
+			if (!factory) throw new Error('shiki: no factory export');
+			return await factory({ themes: [LIGHT, DARK], langs: [] });
+		} catch (err) {
+			loadFailed = true;
+			if (typeof console !== 'undefined') {
+				// eslint-disable-next-line no-console
+				console.info('[dom-studio] Shiki CDN unavailable; using plain code blocks.', err?.message);
+			}
+			return null;
+		}
+	})();
+
+	return highlighterPromise;
+}
+
+/**
+ * Loads one bundled language grammar and shares concurrent requests for it.
+ *
+ * @param {object} highlighter Shiki highlighter instance.
+ * @param {string} lang Normalized bundled language key.
+ * @returns {Promise<void>} Resolves when the language grammar is available.
+ */
+async function ensureLanguage(highlighter, lang) {
+	if (!languagePromises.has(lang)) {
+		languagePromises.set(lang, highlighter.loadLanguage(lang));
+	}
+
+	try {
+		await languagePromises.get(lang);
+	} catch (err) {
+		languagePromises.delete(lang);
+		throw err;
+	}
+}
+
+/**
+ * Normalizes public language names and aliases to a bundled Shiki grammar.
+ *
+ * @param {string} lang Public language key.
+ * @param {string} fallback Bundled grammar used for unknown values.
+ * @returns {string} Normalized bundled language key.
+ */
+export function normalizeCodeLanguage(lang, fallback = 'html') {
+	const normalizedLang = LANG_ALIASES[lang] || lang;
+	return LANGS.includes(normalizedLang) ? normalizedLang : fallback;
+}
+
+/**
+ * Resolves a language name to the preferred value used by DOM Studio controls.
+ *
+ * @param {string} lang Public or normalized language key.
+ * @returns {string} Supported DOM Studio language option value.
+ */
+export function codeLanguageOptionValue(lang) {
+	const normalizedLang = normalizeCodeLanguage(lang, 'text');
+	const option = CODE_LANGUAGE_OPTIONS.find((candidate) => normalizeCodeLanguage(candidate.value) === normalizedLang);
+	return option?.value || 'txt';
+}
+
+/**
+ * Highlights source code with Shiki when available.
+ *
+ * @param {string} code Source code to highlight.
+ * @param {string} lang Source language key.
+ * @param {'inherit' | 'light' | 'dark'} themeMode Syntax theme mode.
+ * @returns {Promise<string|null>} Highlighted HTML, or null for caller fallback.
+ */
+export async function highlight(code, lang = 'vue', themeMode = 'inherit') {
+	if (!code) return null;
+	const h = await getHighlighter();
+	if (!h) return null;
+	try {
+		const resolvedLang = normalizeCodeLanguage(lang);
+		await ensureLanguage(h, resolvedLang);
+		const themeOptions = themeMode === 'light'
+			? { theme: LIGHT }
+			: { themes: { light: LIGHT, dark: DARK } };
+		return h.codeToHtml(code, { lang: resolvedLang, ...themeOptions });
+	} catch {
+		return null;
+	}
+}

package/src/pages/lib/vue/floatingTeleportTarget.js

@@ -0,0 +1,23 @@
+/**
+ * Resolve the safest target for Vue Teleport-based floating UI.
+ *
+ * Floating controls normally portal to the document body so they can escape
+ * local overflow. Modal dialogs and drawers make the rest of the document
+ * inert, so a body-level portal can be mistaken for a backdrop click. Targeting
+ * the nearest modal interaction tree keeps the floating panel inside the focus
+ * trap while preserving document-level fallback behavior.
+ *
+ * @param {Element|null|undefined} source Element mounted inside the floating control.
+ * @returns {Element|string} Teleport target element, or `'body'` before the DOM is available.
+ */
+export function resolveFloatingTeleportTarget(source) {
+	const nearestDialog = typeof source?.closest === 'function'
+		? source.closest('dom-dialog')
+		: null;
+	const nearestDrawer = typeof source?.closest === 'function'
+		? source.closest('dom-drawer')
+		: null;
+	const drawerPanel = nearestDrawer?.querySelector?.('[data-panel]') || null;
+	const ownerDocument = source?.ownerDocument || (typeof document !== 'undefined' ? document : null);
+	return nearestDialog || drawerPanel || nearestDrawer || ownerDocument?.body || 'body';
+}