@moku-labs/web 1.9.0 → 1.11.0

package/dist/index.cjs

@@ -36,6 +36,7 @@ remark_parse = require_convention.__toESM(remark_parse, 1);
 let remark_rehype = require("remark-rehype");
 remark_rehype = require_convention.__toESM(remark_rehype, 1);
 let unist_util_visit = require("unist-util-visit");
+let preact_jsx_runtime = require("preact/jsx-runtime");
 let hast_util_sanitize = require("hast-util-sanitize");
 let reading_time = require("reading-time");
 reading_time = require_convention.__toESM(reading_time, 1);
@@ -1582,13 +1583,14 @@ function validateContentConfig(config) {
 }
 /**
 * Validates the `fileSystemContent` provider options (fail-fast at provider
-* construction). Throws when `mermaid` is enabled without `trustedContent: true`:
-* mermaid output is raw inline SVG, which the sanitize pass (the untrusted-content
-* XSS boundary) would strip — so the combination can never work. Errors use the
-* `[web]` prefix.
+* construction). Throws when `mermaid` or `embed` is enabled without
+* `trustedContent: true`: both emit raw HTML (inline SVG / the embed facade),
+* which the sanitize pass (the untrusted-content XSS boundary) would strip — so
+* the combination can never work. Errors use the `[web]` prefix.
 *
 * @param options - The provider options to validate.
-* @throws {Error} If `mermaid` is enabled while `trustedContent` is not `true`.
+* @throws {Error} If `mermaid` or `embed` is enabled while `trustedContent` is
+* not `true`.
 * @example
 * ```ts
 * validateFileSystemContentOptions({ contentDir: "./content", trustedContent: true, mermaid: true });
@@ -1596,6 +1598,7 @@ function validateContentConfig(config) {
 */
 function validateFileSystemContentOptions(options) {
 	if (Boolean(options.mermaid) && options.trustedContent !== true) throw new Error("[web] content: `mermaid` requires `trustedContent: true`.\n  Mermaid diagrams render to raw inline SVG, which the sanitize pass would strip.\n  Set trustedContent: true ONLY for fully author-controlled Markdown.");
+	if (Boolean(options.embed) && options.trustedContent !== true) throw new Error("[web] content: `embed` requires `trustedContent: true`.\n  Embed directives render to a raw-HTML facade, which the sanitize pass would strip\n  (and embedding third-party iframes is never safe for untrusted Markdown).\n  Set trustedContent: true ONLY for fully author-controlled Markdown.");
 }
 //#endregion
 //#region src/plugins/content/index.ts
@@ -4051,19 +4054,24 @@ function readCachedContent(ctx) {
 //#endregion
 //#region src/plugins/build/phases/content-images.ts
 /**
-* @file build phase — content-images. Copies each article's co-located image directory
-* (`<contentDir>/<slug>/images/`) to a single shared output dir (`<outDir>/<slug>/images/`) reused by
-* every locale, matching the absolute `/<slug>/images/...` URLs the content renderer emits. Gated by
-* `config.images`.
+* @file build phase — content-images. Copies each article's co-located asset
+* directories (`<contentDir>/<slug>/<dir>/`, e.g. `images/` or a pre-built
+* `game/` embed bundle) to a single shared output location
+* (`<outDir>/<slug>/<dir>/`) reused by every locale, matching the absolute
+* `/<slug>/<dir>/...` URLs the content renderer emits (image src + `::embed`
+* src). Dot- and underscore-prefixed dirs are treated as private and skipped.
+* Gated by `config.images`.
 */
-/** Conventional per-article image subdirectory name (alongside `<slug>/<locale>.md`). */
-const ARTICLE_IMAGE_DIR = "images";
 /**
-* Copy every article's co-located `images/` directory to `<outDir>/<slug>/images/`. No-op when
-* `config.images` is false or the content directory does not exist.
+* Copy every article's co-located asset directories to `<outDir>/<slug>/<dir>/`.
+* Each direct subdirectory of `<contentDir>/<slug>/` rides along (the
+* conventional `images/` dir plus any other bundle, like an `::embed` game),
+* except `.`/`_`-prefixed dirs (private). The `.md` source files are never
+* copied (only directories are). No-op when `config.images` is false or the
+* content directory does not exist.
 *
 * @param ctx - Plugin context (provides `config`, `log`, `require`).
-* @returns The number of directories copied (one per article that has an `images/` dir).
+* @returns The number of articles that had at least one asset directory copied.
 * @example
 * ```ts
 * const copied = await copyContentImages(ctx);
@@ -4082,14 +4090,20 @@ async function copyContentImages(ctx) {
 		});
 		return 0;
 	}
-	const entries = await (0, node_fs_promises.readdir)(contentDir, { withFileTypes: true });
+	const articleDirectories = await (0, node_fs_promises.readdir)(contentDir, { withFileTypes: true });
 	let copied = 0;
-	for (const entry of entries) {
-		if (!entry.isDirectory()) continue;
-		const source = node_path$1.default.join(contentDir, entry.name, ARTICLE_IMAGE_DIR);
-		if (!(0, node_fs.existsSync)(source)) continue;
-		await (0, node_fs_promises.cp)(source, node_path$1.default.join(ctx.config.outDir, entry.name, ARTICLE_IMAGE_DIR), { recursive: true });
-		copied += 1;
+	for (const article of articleDirectories) {
+		if (!article.isDirectory()) continue;
+		const articleDir = node_path$1.default.join(contentDir, article.name);
+		const assetDirectories = await (0, node_fs_promises.readdir)(articleDir, { withFileTypes: true });
+		let copiedAny = false;
+		for (const asset of assetDirectories) {
+			if (!asset.isDirectory()) continue;
+			if (asset.name.startsWith(".") || asset.name.startsWith("_")) continue;
+			await (0, node_fs_promises.cp)(node_path$1.default.join(articleDir, asset.name), node_path$1.default.join(ctx.config.outDir, article.name, asset.name), { recursive: true });
+			copiedAny = true;
+		}
+		if (copiedAny) copied += 1;
 	}
 	ctx.log.debug("build:content-images", { copied });
 	return copied;
@@ -11312,6 +11326,89 @@ function disposeSpa() {
 	}
 }
 //#endregion
+//#region src/plugins/spa/lazy-embed.ts
+/**
+* @file `lazyEmbed` island — activates the static embed facades emitted by the
+* content pipeline's `::embed` directive (pipeline/embed.ts). Mounts on every
+* `[data-component="lazy-embed"]` figure; a click on the facade's button swaps
+* it for the real `<iframe loading="lazy">`. Until that click the embedded
+* document costs the page nothing — no request, no third-party JS, no
+* scroll-jacking. Register it in `pluginConfigs.spa.components`; all visual
+* chrome (`.lazy-embed*` classes) is consumer CSS.
+*/
+/** CSS class on the injected `<iframe>` (consumer CSS sizes it). */
+const EMBED_FRAME_CLASS = "lazy-embed-frame";
+/**
+* Swap a facade `<figure>`'s content for its real `<iframe>`. The iframe
+* carries `loading="lazy"` plus fullscreen permission, and the figure gains
+* `data-embed-active` so consumer CSS can restyle the activated state.
+*
+* @param figure - The facade element carrying `data-embed-src`/`data-embed-title`.
+* @example
+* ```ts
+* activateEmbed(figure);
+* ```
+*/
+function activateEmbed(figure) {
+	const src = figure.dataset.embedSrc;
+	if (!src) return;
+	const iframe = document.createElement("iframe");
+	iframe.src = src;
+	iframe.title = figure.dataset.embedTitle ?? "";
+	iframe.className = EMBED_FRAME_CLASS;
+	iframe.setAttribute("loading", "lazy");
+	iframe.allow = "fullscreen; autoplay; gamepad";
+	iframe.allowFullscreen = true;
+	figure.replaceChildren(iframe);
+	figure.dataset.embedActive = "";
+}
+/**
+* Shared click handler (module-level so mount/unmount detach the same
+* reference): any click on the not-yet-active facade activates the embed. It
+* fires on the whole facade — not a specific button class — so a consumer's
+* custom facade markup (see content `embed.facade`) works without re-wiring;
+* the default facade's `<button>` keeps it keyboard-accessible. Once active
+* (`data-embed-active`), clicks fall through to the live iframe.
+*
+* @param event - The click event from the facade figure.
+* @example
+* ```ts
+* element.addEventListener("click", onFacadeClick);
+* ```
+*/
+function onFacadeClick(event) {
+	const figure = event.currentTarget;
+	if (!(figure instanceof HTMLElement)) return;
+	if (figure.dataset.embedActive !== void 0) return;
+	activateEmbed(figure);
+}
+/**
+* Lazy-embed island: facade button click → real `<iframe loading="lazy">`.
+* The companion of the content pipeline's `::embed` directive.
+*/
+const lazyEmbed = createComponent("lazy-embed", {
+	/**
+	* Bind the activation click handler when a facade mounts.
+	*
+	* @param ctx - The island lifecycle context.
+	* @example
+	* onMount(ctx);
+	*/
+	onMount(ctx) {
+		ctx.el.addEventListener("click", onFacadeClick);
+	},
+	/**
+	* Remove the activation click handler when the facade is destroyed.
+	*
+	* @param ctx - The island lifecycle context.
+	* @example
+	* onDestroy(ctx);
+	*/
+	onDestroy(ctx) {
+		ctx.el.removeEventListener("click", onFacadeClick);
+	}
+});
+//#endregion
 //#region src/plugins/spa/index.ts
 /**
 * @file spa — Complex Plugin (WIRING ONLY, ≤30 lines). All logic lives in the
@@ -11586,6 +11683,230 @@ function parseFrontmatter(raw, config) {
 	};
 }
 //#endregion
+//#region src/plugins/content/pipeline/embed-facade.tsx
+/** CSS class on the facade's activation button. */
+const EMBED_BUTTON_CLASS = "lazy-embed-button";
+/** CSS class on the title span inside the activation button. */
+const EMBED_TITLE_CLASS = "lazy-embed-title";
+/**
+* Default `::embed` facade inner content: a single labelled `<button>` carrying
+* the embed title. The companion `lazyEmbed` island activates the embed on a
+* click anywhere in the facade, so the button is the keyboard-accessible
+* control. Provided as the default and as a composable building block for custom
+* facades.
+*
+* @param props - The embed facade props (only `title` is used by the default).
+* @returns The facade inner-content VNode.
+* @example
+* ```tsx
+* // Compose the default inside a richer custom facade:
+* const MyFacade = (p: EmbedFacadeProps) => (
+*   <div class="poster"><img src={p.attributes.poster} alt="" /><EmbedFacadeButton {...p} /></div>
+* );
+* ```
+*/
+function EmbedFacadeButton(props) {
+	return /* @__PURE__ */ (0, preact_jsx_runtime.jsx)("button", {
+		type: "button",
+		class: EMBED_BUTTON_CLASS,
+		"aria-label": `Load embed: ${props.title}`,
+		children: /* @__PURE__ */ (0, preact_jsx_runtime.jsx)("span", {
+			class: EMBED_TITLE_CLASS,
+			children: props.title
+		})
+	});
+}
+//#endregion
+//#region src/plugins/content/pipeline/embed.ts
+/** CSS class on the `<figure>` facade wrapping each embed. */
+const EMBED_FIGURE_CLASS = "lazy-embed";
+/** `data-component` name binding the facade to the `lazyEmbed` SPA island. */
+const EMBED_COMPONENT_NAME = "lazy-embed";
+/**
+* Type guard for an `::embed` leaf directive.
+*
+* @param node - AST node to test.
+* @returns `true` when the node is an `::embed` leaf directive.
+* @example
+* ```ts
+* if (isEmbedDirective(node)) console.log(node.attributes?.src);
+* ```
+*/
+function isEmbedDirective(node) {
+	return node.type === "leafDirective" && node.name === "embed";
+}
+/**
+* Escape a string for safe interpolation into a double-quoted HTML attribute.
+*
+* @param value - The raw attribute value.
+* @returns The escaped value.
+* @example
+* ```ts
+* escapeAttribute('He said "hi" & left'); // "He said &quot;hi&quot; &amp; left"
+* ```
+*/
+function escapeAttribute(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
+}
+/**
+* Validate an embed `src`. Three forms are embeddable: an `http(s)` URL, a
+* root-relative path (`/x`), or a co-located relative path (`./x`, `../x`,
+* `x/…`) resolved later against `/<slug>/`. Everything else — protocol-relative
+* (`//host`), `javascript:`, `data:`, any other scheme — is rejected.
+*
+* @param src - The raw `src` attribute value.
+* @returns `true` when the URL/path is embeddable.
+* @example
+* ```ts
+* isEmbeddableUrl("https://game.example.com/"); // true
+* isEmbeddableUrl("./game/index.html"); // true (co-located)
+* isEmbeddableUrl("javascript:alert(1)"); // false
+* ```
+*/
+function isEmbeddableUrl(src) {
+	if (src === "") return false;
+	if (src.startsWith("//")) return false;
+	if (/^[a-z][a-z0-9+.-]*:/i.test(src)) return /^https?:\/\//i.test(src);
+	return true;
+}
+/**
+* Parse + validate the optional `width`/`height` directive attributes. Both
+* must be supplied together, each a positive integer count of pixels; the pair
+* is used to reserve the facade box at its true aspect ratio. Returns
+* `undefined` when neither is set.
+*
+* @param width - Raw `width` attribute (or undefined).
+* @param height - Raw `height` attribute (or undefined).
+* @returns The parsed dimensions, or `undefined` when both are absent.
+* @throws {Error} When only one of the pair is set, or a value is not a
+* positive integer.
+* @example
+* ```ts
+* parseDimensions("400", "711"); // { width: 400, height: 711 }
+* parseDimensions(undefined, undefined); // undefined
+* ```
+*/
+function parseDimensions(width, height) {
+	const hasWidth = width !== void 0 && width !== null && width !== "";
+	const hasHeight = height !== void 0 && height !== null && height !== "";
+	if (!hasWidth && !hasHeight) return void 0;
+	if (!hasWidth || !hasHeight) throw new Error("[web] content: `::embed` width and height must be set together (got only one).");
+	if (!/^\d+$/.test(width) || !/^\d+$/.test(height) || width === "0" || height === "0") throw new Error(`[web] content: \`::embed\` width/height must be positive integers in pixels (got "${width}"×"${height}").`);
+	return {
+		width: Number(width),
+		height: Number(height)
+	};
+}
+/**
+* Collect the directive's raw attribute bag into a plain string record, dropping
+* `null`/`undefined` values (so a custom facade can read arbitrary extra options).
+*
+* @param attributes - The raw directive attributes (or undefined).
+* @returns A string-valued attribute record.
+* @example
+* ```ts
+* collectAttributes({ src: "x", poster: "/p.jpg", flag: null }); // { src: "x", poster: "/p.jpg" }
+* ```
+*/
+function collectAttributes(attributes) {
+	const out = {};
+	for (const [key, value] of Object.entries(attributes ?? {})) if (typeof value === "string") out[key] = value;
+	return out;
+}
+/**
+* Build the static facade HTML for one embed: the framework-owned `<figure>`
+* (island hooks in data attributes; optional reserved-box `aspect-ratio`/`max-width`
+* inline style when dimensions are given) wrapping the facade component's inner
+* content, SSR'd to static markup. The wrapper carries `data-embed-src` (raw —
+* the provider resolves a relative src) so neither the island contract nor the
+* URL rewrite depend on the consumer's markup.
+*
+* @param facade - The facade component (default {@link EmbedFacadeButton}).
+* @param props - The facade props (`src`, `title`, optional `width`/`height`, raw `attributes`).
+* @param dimensions - Optional reserved-box pixel dimensions.
+* @returns The facade HTML string.
+* @example
+* ```ts
+* embedFacadeHtml(EmbedFacadeButton, { src: "https://g/", title: "G", attributes: {} });
+* ```
+*/
+function embedFacadeHtml(facade, props, dimensions) {
+	return `<figure class="${EMBED_FIGURE_CLASS}" data-component="${EMBED_COMPONENT_NAME}" data-embed-src="${escapeAttribute(props.src)}" data-embed-title="${escapeAttribute(props.title)}"${dimensions ? ` data-embed-width="${dimensions.width}" data-embed-height="${dimensions.height}" style="aspect-ratio: ${dimensions.width} / ${dimensions.height}; max-width: ${dimensions.width}px;"` : ""}>${(0, preact_render_to_string.renderToString)((0, preact.h)(facade, props))}</figure>`;
+}
+/**
+* Normalize the provider's `embed` config value (`boolean | options`) to a plain
+* {@link EmbedOptions} object for the transform factory.
+*
+* @param embed - The raw `FileSystemContentOptions.embed` value (truthy).
+* @returns The options object (`{}` for the bare `true` form).
+* @example
+* ```ts
+* normalizeEmbedOptions(true); // {}
+* normalizeEmbedOptions({ facade: MyFacade });
+* ```
+*/
+function normalizeEmbedOptions(embed) {
+	return typeof embed === "boolean" ? {} : embed;
+}
+/**
+* Mdast transformer rewriting every `::embed` leaf directive to its facade
+* HTML node. A directive missing `src`/`title`, carrying a non-embeddable URL,
+* or carrying invalid `width`/`height`, fails the build with the offending
+* value quoted.
+*
+* @param facade - The facade component to render the inner content with.
+* @param tree - The mdast tree to mutate.
+* @throws {Error} When an `::embed` directive is missing `src` or `title`, its
+* `src` is not embeddable, or its dimensions are invalid.
+* @example
+* ```ts
+* embedTransform(EmbedFacadeButton, tree);
+* ```
+*/
+function embedTransform(facade, tree) {
+	(0, unist_util_visit.visit)(tree, (node, index, parent) => {
+		if (!isEmbedDirective(node)) return;
+		if (parent === void 0 || index === void 0) return;
+		const src = node.attributes?.src ?? "";
+		const title = node.attributes?.title ?? "";
+		if (src === "" || title === "") throw new Error("[web] content: `::embed` requires both `src` and `title` attributes, e.g. ::embed{src=\"https://…\" title=\"…\"}.");
+		if (!isEmbeddableUrl(src)) throw new Error(`[web] content: \`::embed\` src must be an http(s) URL, a root-relative path, or a co-located relative path (got "${src}").`);
+		const dimensions = parseDimensions(node.attributes?.width, node.attributes?.height);
+		const html = {
+			type: "html",
+			value: embedFacadeHtml(facade, {
+				src,
+				title,
+				...dimensions ? {
+					width: dimensions.width,
+					height: dimensions.height
+				} : {},
+				attributes: collectAttributes(node.attributes)
+			}, dimensions)
+		};
+		parent.children[index] = html;
+	});
+}
+/**
+* Remark transform factory: rewrites `::embed{src="…" title="…"}` leaf directives
+* into static click-to-activate facades (no iframe until the reader clicks — see
+* the file header). Opt-in via the provider's `embed` option; requires
+* `trustedContent: true` because the facade is raw HTML the sanitize pass would
+* strip. The facade's inner content is rendered by `options.facade` (a consumer
+* Preact component) or the built-in {@link EmbedFacadeButton}.
+*
+* @param options - Embed options (the optional `facade` component).
+* @returns An mdast tree transformer.
+* @example
+* ```ts
+* unified().use(embedPlugin, { facade: MyFacade });
+* ```
+*/
+function embedPlugin(options = {}) {
+	const facade = options.facade ?? EmbedFacadeButton;
+	return (tree) => embedTransform(facade, tree);
+}
+//#endregion
 //#region src/plugins/content/pipeline/mermaid.ts
 /** CSS class on the `<figure>` wrapper around each rendered diagram. */
 const MERMAID_FIGURE_CLASS = "mermaid-diagram";
@@ -11869,14 +12190,17 @@ function sectionDividerPlugin() {
 }
 /**
 * The hardcoded framework default remark (Markdown-AST) plugins, in order:
-* parse, frontmatter, gfm, directive, pull-quote, the OPT-IN mermaid transform,
-* then the mdast→hast bridge (`remark-rehype` with `allowDangerousHtml`).
-* Pull-quote and mermaid run on the mdast before the bridge — pull-quote so the
-* directive carries its `hName`/`hProperties`, mermaid so the fence is replaced
-* with raw SVG HTML before Shiki could ever claim the code block.
-*
-* @param config - Optional provider configuration; only `mermaid` is read here
-* (truthy enables the mermaid transform at its fixed mdast position).
+* parse, frontmatter, gfm, directive, pull-quote, the OPT-IN embed + mermaid
+* transforms, then the mdast→hast bridge (`remark-rehype` with
+* `allowDangerousHtml`). Pull-quote, embed and mermaid run on the mdast before
+* the bridge — pull-quote so the directive carries its `hName`/`hProperties`,
+* embed so the directive is replaced with its raw facade HTML, mermaid so the
+* fence is replaced with raw SVG HTML before Shiki could ever claim the code
+* block.
+*
+* @param config - Optional provider configuration; only the opt-in flags are
+* read here: `mermaid` and `embed` (each truthy value enables its transform at
+* a fixed mdast position).
 * @returns The ordered default remark pluggables.
 * @example
 * ```ts
@@ -11891,6 +12215,7 @@ function defaultRemarkPlugins(config) {
 		remark_directive.default,
 		pullQuotePlugin
 	];
+	if (config?.embed) plugins.push([embedPlugin, normalizeEmbedOptions(config.embed)]);
 	if (config?.mermaid) plugins.push([remarkMermaidDiagrams, normalizeMermaidOptions(config.mermaid)]);
 	plugins.push([remark_rehype.default, { allowDangerousHtml: true }]);
 	return plugins;
@@ -12132,6 +12457,8 @@ function calculateReadingTime(text) {
 */
 /** Matches an `<img>` `src` that points at the co-located `images/` dir (relative or root-relative). */
 const RELATIVE_IMAGE_SRC = /(<img\b[^>]*?\bsrc=")(?:\.?\/)?images\//g;
+/** Matches the `data-embed-src` of an `::embed` facade (value captured for path resolution). */
+const EMBED_SRC_ATTR = /(\bdata-embed-src=")([^"]*)(")/g;
 /**
 * Build a canonical article URL for a locale + slug.
 *
@@ -12162,6 +12489,56 @@ function rewriteImageUrls(html, slug) {
 	return html.replaceAll(RELATIVE_IMAGE_SRC, `$1/${slug}/images/`);
 }
 /**
+* Resolve an `::embed` `src` to the URL the iframe should load. Absolute targets
+* (`http(s)://…`, root-relative `/…`) pass through unchanged; a co-located
+* relative path (`./game/index.html`, `../x`, `game/x`) is resolved against the
+* article base `/<slug>/` into the single shared absolute path the content-assets
+* build phase copies the bundle to — so it loads identically from every locale
+* page (mirroring how co-located images resolve). Any `?query`/`#hash` is
+* preserved verbatim.
+*
+* @param value - The raw `data-embed-src` value.
+* @param slug - Article directory name.
+* @returns The resolved embed URL.
+* @example
+* ```ts
+* resolveEmbedSource("./game/index.html", "post"); // "/post/game/index.html"
+* resolveEmbedSource("https://x.dev/", "post"); // "https://x.dev/"
+* ```
+*/
+function resolveEmbedSource(value, slug) {
+	if (/^https?:\/\//i.test(value) || value.startsWith("/")) return value;
+	const tailIndex = value.search(/[?#]/);
+	const rawPath = tailIndex === -1 ? value : value.slice(0, tailIndex);
+	const tail = tailIndex === -1 ? "" : value.slice(tailIndex);
+	const out = [];
+	for (const segment of `${slug}/${rawPath}`.split("/")) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") {
+			out.pop();
+			continue;
+		}
+		out.push(segment);
+	}
+	const trailingSlash = rawPath === "" || rawPath.endsWith("/") ? "/" : "";
+	return `/${out.join("/")}${trailingSlash}${tail}`;
+}
+/**
+* Rewrite every `::embed` facade's relative `data-embed-src` to its shared
+* absolute `/<slug>/…` path (no-op for already-absolute targets).
+*
+* @param html - The rendered article HTML.
+* @param slug - Article directory name.
+* @returns The HTML with embed `src`s resolved.
+* @example
+* ```ts
+* rewriteEmbedUrls('<figure data-embed-src="./g/">', "post"); // '… data-embed-src="/post/g/"'
+* ```
+*/
+function rewriteEmbedUrls(html, slug) {
+	return html.replaceAll(EMBED_SRC_ATTR, (_match, prefix, value, suffix) => `${prefix}${resolveEmbedSource(value, slug)}${suffix}`);
+}
+/**
 * Discover slug-like subdirectories of the content root (direct children not
 * starting with `.` or `_`), sorted alphabetically for deterministic ordering.
 *
@@ -12240,7 +12617,7 @@ function fileSystemContent(options) {
 			state.dirtyPaths.delete(filePath);
 			const { frontmatter, body } = parseFrontmatter(raw, options);
 			const processor = ensureProcessor(state, options);
-			const html = rewriteImageUrls(String(await processor.process(body)), slug);
+			const html = rewriteEmbedUrls(rewriteImageUrls(String(await processor.process(body)), slug), slug);
 			const { readingTime, wordCount } = calculateReadingTime(body);
 			return {
 				frontmatter,
@@ -12394,6 +12771,7 @@ Object.defineProperty(exports, "Deploy", {
 		return types_exports$4;
 	}
 });
+exports.EmbedFacadeButton = EmbedFacadeButton;
 Object.defineProperty(exports, "Env", {
 	enumerable: true,
 	get: function() {
@@ -12446,6 +12824,7 @@ exports.headPlugin = headPlugin;
 exports.hreflang = hreflang;
 exports.i18nPlugin = i18nPlugin;
 exports.jsonLd = jsonLd;
+exports.lazyEmbed = lazyEmbed;
 exports.logPlugin = logPlugin;
 exports.meta = meta;
 exports.og = og;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { ComponentChildren, VNode } from "preact";
+import { ComponentChildren, FunctionComponent, VNode } from "preact";
 import { EmitFn } from "@moku-labs/core";
 import { BundledTheme, ThemeRegistrationAny } from "shiki";
 import { Pluggable, Processor } from "unified";
@@ -2671,7 +2671,7 @@ type Api$1 = {
  */
 declare const cliPlugin: import("@moku-labs/core").PluginInstance<"cli", Config$1, State$1, Api$1, {}> & Record<never, never>;
 declare namespace types_d_exports$2 {
-  export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, FileSystemContentOptions, Frontmatter, LoadAllOptions, MermaidDiagramOptions, State };
+  export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, EmbedFacade, EmbedFacadeProps, EmbedOptions, FileSystemContentOptions, Frontmatter, LoadAllOptions, MermaidDiagramOptions, State };
 }
 /**
  * YAML frontmatter parsed from each article file.
@@ -2815,6 +2815,55 @@ type MermaidDiagramOptions = {
    */
   renderDiagrams?: (sources: readonly string[], mermaidConfig?: Record<string, unknown>) => Promise<readonly string[]>;
 };
+/**
+ * Props handed to an `::embed` facade component (the click-to-activate placeholder
+ * the framework renders to static markup at build time). `width`/`height` are the
+ * parsed pixel dimensions when the directive set them; `attributes` is the full raw
+ * directive attribute bag, so a custom facade can read arbitrary extra options
+ * (e.g. `::embed{… poster="/p.jpg" label="Play"}`).
+ *
+ * @example
+ * ```tsx
+ * const Facade = ({ title, attributes }: EmbedFacadeProps) => (
+ *   <button type="button" class="lazy-embed-button">
+ *     {attributes.poster ? <img src={attributes.poster} alt="" /> : null}
+ *     <span class="lazy-embed-title">{title}</span>
+ *   </button>
+ * );
+ * ```
+ */
+type EmbedFacadeProps = {
+  /** The embed target exactly as written in the directive (the provider resolves it later). */src: string; /** The human-readable embed title (default label + iframe title). */
+  title: string; /** Reserved-box width in pixels, when the directive set `width`/`height`. */
+  width?: number; /** Reserved-box height in pixels, when the directive set `width`/`height`. */
+  height?: number; /** The full raw directive attribute bag (custom options live here). */
+  attributes: Readonly<Record<string, string>>;
+};
+/**
+ * A consumer-supplied facade component: a Preact function component over
+ * {@link EmbedFacadeProps}, rendered (at build time, to static markup) as the
+ * facade's inner content — inside the framework-owned `<figure>` that carries the
+ * island hooks + reserved-box sizing. Defaults to the built-in `EmbedFacadeButton`.
+ */
+type EmbedFacade = FunctionComponent<EmbedFacadeProps>;
+/**
+ * Options for the `::embed` lazy-iframe feature (the `embed` key of
+ * {@link FileSystemContentOptions}). `embed: true` uses the default facade;
+ * `embed: { facade }` swaps in a consumer Preact component for the placeholder.
+ *
+ * @example
+ * ```ts
+ * fileSystemContent({ contentDir: "./content", trustedContent: true, embed: { facade: MyFacade } });
+ * ```
+ */
+type EmbedOptions = {
+  /**
+   * Consumer Preact component rendering the facade's inner content (SSR'd to
+   * static markup at build — no client JS). Receives {@link EmbedFacadeProps}.
+   * Defaults to the built-in `EmbedFacadeButton`.
+   */
+  facade?: EmbedFacade;
+};
 /**
  * Options for the node filesystem provider {@link ContentProvider} `fileSystemContent`.
  * These are the markdown-pipeline + source concerns that used to live on the content
@@ -2849,6 +2898,16 @@ type FileSystemContentOptions = {
    * (plus playwright with an installed browser). Defaults to disabled.
    */
   mermaid?: boolean | MermaidDiagramOptions;
+  /**
+   * Lazy iframe embeds: rewrite `::embed{src="…" title="…"}` leaf directives
+   * into static click-to-activate facades (no iframe — and none of the target's
+   * network/JS cost — until the reader clicks). Pair with the `lazyEmbed` SPA
+   * island, which swaps the facade for the real `<iframe loading="lazy">`.
+   * `true` enables with the default facade; an object passes {@link EmbedOptions}
+   * (e.g. a consumer `facade` Preact component). Requires `trustedContent: true`
+   * (the facade is raw HTML the sanitize pass would strip). Defaults to disabled.
+   */
+  embed?: boolean | EmbedOptions;
 };
 /**
  * Internal mutable state of the filesystem provider: the lazy unified processor and
@@ -3486,6 +3545,13 @@ declare const sitePlugin: import("@moku-labs/core").PluginInstance<"site", Confi
  */
 declare function createComponent(name: string, hooks: ComponentHooks): ComponentDef;
 //#endregion
+//#region src/plugins/spa/lazy-embed.d.ts
+/**
+ * Lazy-embed island: facade button click → real `<iframe loading="lazy">`.
+ * The companion of the content pipeline's `::embed` directive.
+ */
+declare const lazyEmbed: ComponentDef;
+//#endregion
 //#region src/plugins/spa/index.d.ts
 /**
  * SPA plugin — progressive client-side navigation layered over the static site:
@@ -3581,6 +3647,26 @@ declare function cloudflareBindings(): EnvProvider;
  */
 declare function fileSystemContent(options: FileSystemContentOptions): ContentProvider;
 //#endregion
+//#region src/plugins/content/pipeline/embed-facade.d.ts
+/**
+ * Default `::embed` facade inner content: a single labelled `<button>` carrying
+ * the embed title. The companion `lazyEmbed` island activates the embed on a
+ * click anywhere in the facade, so the button is the keyboard-accessible
+ * control. Provided as the default and as a composable building block for custom
+ * facades.
+ *
+ * @param props - The embed facade props (only `title` is used by the default).
+ * @returns The facade inner-content VNode.
+ * @example
+ * ```tsx
+ * // Compose the default inside a richer custom facade:
+ * const MyFacade = (p: EmbedFacadeProps) => (
+ *   <div class="poster"><img src={p.attributes.poster} alt="" /><EmbedFacadeButton {...p} /></div>
+ * );
+ * ```
+ */
+declare function EmbedFacadeButton(props: EmbedFacadeProps): VNode;
+//#endregion
 //#region src/index.d.ts
 /**
  * Create and initialize a `@moku-labs/web` application — the Layer-3 entry point.
@@ -3687,4 +3773,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  */
 declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$8, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", LogConfig, LogState, LogApi>, import("@moku-labs/core").CorePluginInstance<"env", EnvConfig, EnvState, EnvApi>]>>;
 //#endregion
-export { types_d_exports as Build, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, types_d_exports$5 as Env, types_d_exports$6 as Head, types_d_exports$7 as Log, types_d_exports$8 as Router, types_d_exports$9 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_d_exports as Build, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, type EmbedFacade, EmbedFacadeButton, type EmbedFacadeProps, type EmbedOptions, types_d_exports$5 as Env, types_d_exports$6 as Head, types_d_exports$7 as Log, types_d_exports$8 as Router, types_d_exports$9 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };