@moku-labs/web 1.9.0 → 1.10.0

package/dist/browser.d.mts

@@ -1734,6 +1734,13 @@ declare const headPlugin: import("@moku-labs/core").PluginInstance<"head", 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:
@@ -2098,6 +2105,15 @@ 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">`.
+   * Requires `trustedContent: true` (the facade is raw HTML the sanitize pass
+   * would strip). Defaults to disabled.
+   */
+  embed?: boolean;
 };
 /**
  * Internal mutable state of the filesystem provider: the lazy unified processor and
@@ -2400,4 +2416,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  */
 declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$5, 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 Content, types_d_exports$1 as Data, types_d_exports$2 as Env, types_d_exports$3 as Head, types_d_exports$4 as Log, types_d_exports$5 as Router, types_d_exports$6 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_d_exports as Content, types_d_exports$1 as Data, types_d_exports$2 as Env, types_d_exports$3 as Head, types_d_exports$4 as Log, types_d_exports$5 as Router, types_d_exports$6 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };

package/dist/browser.mjs

@@ -4428,6 +4428,84 @@ 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): a click on the facade's button activates the embed.
+*
+* @param event - The click event from the facade figure.
+* @example
+* ```ts
+* element.addEventListener("click", onFacadeClick);
+* ```
+*/
+function onFacadeClick(event) {
+	if (!event.target.closest("button.lazy-embed-button")) return;
+	const figure = event.currentTarget;
+	if (figure instanceof HTMLElement) 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
@@ -5115,4 +5193,4 @@ const createApp = core.createApp;
 */
 const createPlugin = core.createPlugin;
 //#endregion
-export { types_exports as Content, types_exports$1 as Data, types_exports$2 as Env, types_exports$3 as Head, types_exports$4 as Log, types_exports$5 as Router, types_exports$6 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_exports as Content, types_exports$1 as Data, types_exports$2 as Env, types_exports$3 as Head, types_exports$4 as Log, types_exports$5 as Router, types_exports$6 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createComponent, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };

package/dist/index.cjs

@@ -1582,13 +1582,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 +1597,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
@@ -11312,6 +11314,84 @@ 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): a click on the facade's button activates the embed.
+*
+* @param event - The click event from the facade figure.
+* @example
+* ```ts
+* element.addEventListener("click", onFacadeClick);
+* ```
+*/
+function onFacadeClick(event) {
+	if (!event.target.closest("button.lazy-embed-button")) return;
+	const figure = event.currentTarget;
+	if (figure instanceof HTMLElement) 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 +11666,121 @@ function parseFrontmatter(raw, config) {
 	};
 }
 //#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";
+/** 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";
+/**
+* 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` URL: only `https:`/`http:` absolute URLs and
+* root-relative paths are embeddable — anything else (`javascript:`, `data:`,
+* scheme-relative, …) fails the build.
+*
+* @param src - The raw `src` attribute value.
+* @returns `true` when the URL is embeddable.
+* @example
+* ```ts
+* isEmbeddableUrl("https://game.example.com/"); // true
+* isEmbeddableUrl("javascript:alert(1)"); // false
+* ```
+*/
+function isEmbeddableUrl(src) {
+	if (src.startsWith("/") && !src.startsWith("//")) return true;
+	return /^https?:\/\//i.test(src);
+}
+/**
+* Build the static facade HTML for one embed: the `<figure>` carrying the
+* target in data attributes plus the activation `<button>` (the button label
+* is the embed's title; visual chrome is consumer CSS).
+*
+* @param src - The validated embed URL.
+* @param title - The human-readable embed title (button label, iframe title).
+* @returns The facade HTML string.
+* @example
+* ```ts
+* embedFacadeHtml("https://game.example.com/", "My Game");
+* ```
+*/
+function embedFacadeHtml(src, title) {
+	const safeSource = escapeAttribute(src);
+	const safeTitle = escapeAttribute(title);
+	return `<figure class="${EMBED_FIGURE_CLASS}" data-component="${EMBED_COMPONENT_NAME}" data-embed-src="${safeSource}" data-embed-title="${safeTitle}"><button type="button" class="${EMBED_BUTTON_CLASS}" aria-label="Load embed: ${safeTitle}"><span class="${EMBED_TITLE_CLASS}">${safeTitle}</span></button></figure>`;
+}
+/**
+* Mdast transformer rewriting every `::embed` leaf directive to its facade
+* HTML node. A directive missing `src`/`title`, or carrying a non-embeddable
+* URL, fails the build with the offending value quoted.
+*
+* @param tree - The mdast tree to mutate.
+* @throws {Error} When an `::embed` directive is missing `src` or `title`, or
+* its `src` is not an embeddable URL.
+* @example
+* ```ts
+* embedTransform(tree);
+* ```
+*/
+function embedTransform(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 or a root-relative path (got "${src}").`);
+		const html = {
+			type: "html",
+			value: embedFacadeHtml(src, title)
+		};
+		parent.children[index] = html;
+	});
+}
+/**
+* Remark transform: 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.
+*
+* @returns An mdast tree transformer.
+* @example
+* ```ts
+* unified().use(embedPlugin);
+* ```
+*/
+function embedPlugin() {
+	return embedTransform;
+}
+//#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 +12064,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 +12089,7 @@ function defaultRemarkPlugins(config) {
 		remark_directive.default,
 		pullQuotePlugin
 	];
+	if (config?.embed) plugins.push(embedPlugin);
 	if (config?.mermaid) plugins.push([remarkMermaidDiagrams, normalizeMermaidOptions(config.mermaid)]);
 	plugins.push([remark_rehype.default, { allowDangerousHtml: true }]);
 	return plugins;
@@ -12446,6 +12645,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

@@ -2849,6 +2849,15 @@ 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">`.
+   * Requires `trustedContent: true` (the facade is raw HTML the sanitize pass
+   * would strip). Defaults to disabled.
+   */
+  embed?: boolean;
 };
 /**
  * Internal mutable state of the filesystem provider: the lazy unified processor and
@@ -3486,6 +3495,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:
@@ -3687,4 +3703,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, 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 };

package/dist/index.d.mts

@@ -2849,6 +2849,15 @@ 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">`.
+   * Requires `trustedContent: true` (the facade is raw HTML the sanitize pass
+   * would strip). Defaults to disabled.
+   */
+  embed?: boolean;
 };
 /**
  * Internal mutable state of the filesystem provider: the lazy unified processor and
@@ -3486,6 +3495,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:
@@ -3687,4 +3703,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, 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 };

package/dist/index.mjs

@@ -1569,13 +1569,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 });
@@ -1583,6 +1584,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
@@ -11299,6 +11301,84 @@ 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): a click on the facade's button activates the embed.
+*
+* @param event - The click event from the facade figure.
+* @example
+* ```ts
+* element.addEventListener("click", onFacadeClick);
+* ```
+*/
+function onFacadeClick(event) {
+	if (!event.target.closest("button.lazy-embed-button")) return;
+	const figure = event.currentTarget;
+	if (figure instanceof HTMLElement) 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
@@ -11573,6 +11653,121 @@ function parseFrontmatter(raw, config) {
 	};
 }
 //#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";
+/** 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";
+/**
+* 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` URL: only `https:`/`http:` absolute URLs and
+* root-relative paths are embeddable — anything else (`javascript:`, `data:`,
+* scheme-relative, …) fails the build.
+*
+* @param src - The raw `src` attribute value.
+* @returns `true` when the URL is embeddable.
+* @example
+* ```ts
+* isEmbeddableUrl("https://game.example.com/"); // true
+* isEmbeddableUrl("javascript:alert(1)"); // false
+* ```
+*/
+function isEmbeddableUrl(src) {
+	if (src.startsWith("/") && !src.startsWith("//")) return true;
+	return /^https?:\/\//i.test(src);
+}
+/**
+* Build the static facade HTML for one embed: the `<figure>` carrying the
+* target in data attributes plus the activation `<button>` (the button label
+* is the embed's title; visual chrome is consumer CSS).
+*
+* @param src - The validated embed URL.
+* @param title - The human-readable embed title (button label, iframe title).
+* @returns The facade HTML string.
+* @example
+* ```ts
+* embedFacadeHtml("https://game.example.com/", "My Game");
+* ```
+*/
+function embedFacadeHtml(src, title) {
+	const safeSource = escapeAttribute(src);
+	const safeTitle = escapeAttribute(title);
+	return `<figure class="${EMBED_FIGURE_CLASS}" data-component="${EMBED_COMPONENT_NAME}" data-embed-src="${safeSource}" data-embed-title="${safeTitle}"><button type="button" class="${EMBED_BUTTON_CLASS}" aria-label="Load embed: ${safeTitle}"><span class="${EMBED_TITLE_CLASS}">${safeTitle}</span></button></figure>`;
+}
+/**
+* Mdast transformer rewriting every `::embed` leaf directive to its facade
+* HTML node. A directive missing `src`/`title`, or carrying a non-embeddable
+* URL, fails the build with the offending value quoted.
+*
+* @param tree - The mdast tree to mutate.
+* @throws {Error} When an `::embed` directive is missing `src` or `title`, or
+* its `src` is not an embeddable URL.
+* @example
+* ```ts
+* embedTransform(tree);
+* ```
+*/
+function embedTransform(tree) {
+	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 or a root-relative path (got "${src}").`);
+		const html = {
+			type: "html",
+			value: embedFacadeHtml(src, title)
+		};
+		parent.children[index] = html;
+	});
+}
+/**
+* Remark transform: 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.
+*
+* @returns An mdast tree transformer.
+* @example
+* ```ts
+* unified().use(embedPlugin);
+* ```
+*/
+function embedPlugin() {
+	return embedTransform;
+}
+//#endregion
 //#region src/plugins/content/pipeline/mermaid.ts
 /** CSS class on the `<figure>` wrapper around each rendered diagram. */
 const MERMAID_FIGURE_CLASS = "mermaid-diagram";
@@ -11856,14 +12051,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
@@ -11878,6 +12076,7 @@ function defaultRemarkPlugins(config) {
 		remarkDirective,
 		pullQuotePlugin
 	];
+	if (config?.embed) plugins.push(embedPlugin);
 	if (config?.mermaid) plugins.push([remarkMermaidDiagrams, normalizeMermaidOptions(config.mermaid)]);
 	plugins.push([remarkRehype, { allowDangerousHtml: true }]);
 	return plugins;
@@ -12351,4 +12550,4 @@ const createApp = core.createApp;
 */
 const createPlugin = core.createPlugin;
 //#endregion
-export { types_exports as Build, types_exports$1 as Cli, types_exports$2 as Content, types_exports$3 as Data, types_exports$4 as Deploy, types_exports$5 as Env, types_exports$6 as Head, types_exports$7 as Log, types_exports$8 as Router, types_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_exports as Build, types_exports$1 as Cli, types_exports$2 as Content, types_exports$3 as Data, types_exports$4 as Deploy, types_exports$5 as Env, types_exports$6 as Head, types_exports$7 as Log, types_exports$8 as Router, types_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 };

package/package.json

@@ -125,5 +125,5 @@
     "test:build-e2e": "bun test src/plugins/build/__tests__/e2e/",
     "test:coverage": "vitest run --project unit --project integration --coverage"
   },
-  "version": "1.9.0"
+  "version": "1.10.0"
 }