@moku-labs/web 1.10.0 → 1.11.0

package/dist/browser.d.mts

@@ -1,5 +1,5 @@
 import { EmitFn } from "@moku-labs/core";
-import { ComponentChildren, VNode } from "preact";
+import { ComponentChildren, FunctionComponent, VNode } from "preact";
 import { BundledTheme, ThemeRegistrationAny } from "shiki";
 import { Pluggable, Processor } from "unified";
 
@@ -1927,7 +1927,7 @@ type DataProvider = {
  */
 declare const dataPlugin: import("@moku-labs/core").PluginInstance<"data", DataConfig, DataState, DataProvider, {}> & Record<never, never>;
 declare namespace types_d_exports {
-  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.
@@ -2071,6 +2071,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
@@ -2110,10 +2159,11 @@ type FileSystemContentOptions = {
    * 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.
+   * `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;
+  embed?: boolean | EmbedOptions;
 };
 /**
  * Internal mutable state of the filesystem provider: the lazy unified processor and

package/dist/browser.mjs

@@ -4466,7 +4466,11 @@ function activateEmbed(figure) {
 }
 /**
 * Shared click handler (module-level so mount/unmount detach the same
-* reference): a click on the facade's button activates the embed.
+* 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
@@ -4475,9 +4479,10 @@ function activateEmbed(figure) {
 * ```
 */
 function onFacadeClick(event) {
-	if (!event.target.closest("button.lazy-embed-button")) return;
 	const figure = event.currentTarget;
-	if (figure instanceof HTMLElement) activateEmbed(figure);
+	if (!(figure instanceof HTMLElement)) return;
+	if (figure.dataset.embedActive !== void 0) return;
+	activateEmbed(figure);
 }
 /**
 * Lazy-embed island: facade button click → real `<iframe loading="lazy">`.

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);
@@ -4053,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);
@@ -4084,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;
@@ -11352,7 +11364,11 @@ function activateEmbed(figure) {
 }
 /**
 * Shared click handler (module-level so mount/unmount detach the same
-* reference): a click on the facade's button activates the embed.
+* 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
@@ -11361,9 +11377,10 @@ function activateEmbed(figure) {
 * ```
 */
 function onFacadeClick(event) {
-	if (!event.target.closest("button.lazy-embed-button")) return;
 	const figure = event.currentTarget;
-	if (figure instanceof HTMLElement) activateEmbed(figure);
+	if (!(figure instanceof HTMLElement)) return;
+	if (figure.dataset.embedActive !== void 0) return;
+	activateEmbed(figure);
 }
 /**
 * Lazy-embed island: facade button click → real `<iframe loading="lazy">`.
@@ -11666,15 +11683,45 @@ 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";
-/** 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.
 *
@@ -11702,83 +11749,162 @@ 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.
+* 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 is embeddable.
+* @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.startsWith("/") && !src.startsWith("//")) return true;
-	return /^https?:\/\//i.test(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;
 }
 /**
-* 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).
+* 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 src - The validated embed URL.
-* @param title - The human-readable embed title (button label, iframe title).
+* @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("https://game.example.com/", "My Game");
+* 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 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>`;
+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`, or carrying a non-embeddable
-* URL, fails the build with the offending value quoted.
+* 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`, or
-* its `src` is not an embeddable URL.
+* @throws {Error} When an `::embed` directive is missing `src` or `title`, its
+* `src` is not embeddable, or its dimensions are invalid.
 * @example
 * ```ts
-* embedTransform(tree);
+* embedTransform(EmbedFacadeButton, tree);
 * ```
 */
-function embedTransform(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 or a root-relative path (got "${src}").`);
+		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(src, title)
+			value: embedFacadeHtml(facade, {
+				src,
+				title,
+				...dimensions ? {
+					width: dimensions.width,
+					height: dimensions.height
+				} : {},
+				attributes: collectAttributes(node.attributes)
+			}, dimensions)
 		};
 		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
+* 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.
+* `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);
+* unified().use(embedPlugin, { facade: MyFacade });
 * ```
 */
-function embedPlugin() {
-	return embedTransform;
+function embedPlugin(options = {}) {
+	const facade = options.facade ?? EmbedFacadeButton;
+	return (tree) => embedTransform(facade, tree);
 }
 //#endregion
 //#region src/plugins/content/pipeline/mermaid.ts
@@ -12089,7 +12215,7 @@ function defaultRemarkPlugins(config) {
 		remark_directive.default,
 		pullQuotePlugin
 	];
-	if (config?.embed) plugins.push(embedPlugin);
+	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;
@@ -12331,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.
 *
@@ -12361,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.
 *
@@ -12439,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,
@@ -12593,6 +12771,7 @@ Object.defineProperty(exports, "Deploy", {
 		return types_exports$4;
 	}
 });
+exports.EmbedFacadeButton = EmbedFacadeButton;
 Object.defineProperty(exports, "Env", {
 	enumerable: true,
 	get: function() {

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
@@ -2854,10 +2903,11 @@ type FileSystemContentOptions = {
    * 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.
+   * `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;
+  embed?: boolean | EmbedOptions;
 };
 /**
  * Internal mutable state of the filesystem provider: the lazy unified processor and
@@ -3597,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.
@@ -3703,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, lazyEmbed, 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 };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { EmitFn } from "@moku-labs/core";
-import { ComponentChildren, VNode } from "preact";
+import { ComponentChildren, FunctionComponent, VNode } from "preact";
 import { Pluggable, Processor } from "unified";
 import { BundledTheme, ThemeRegistrationAny } from "shiki";
 
@@ -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
@@ -2854,10 +2903,11 @@ type FileSystemContentOptions = {
    * 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.
+   * `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;
+  embed?: boolean | EmbedOptions;
 };
 /**
  * Internal mutable state of the filesystem provider: the lazy unified processor and
@@ -3597,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.
@@ -3703,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, lazyEmbed, 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 };

package/dist/index.mjs

@@ -24,6 +24,7 @@ import remarkGfm from "remark-gfm";
 import remarkParse from "remark-parse";
 import remarkRehype from "remark-rehype";
 import { visit } from "unist-util-visit";
+import { jsx } from "preact/jsx-runtime";
 import { defaultSchema } from "hast-util-sanitize";
 import readingTime from "reading-time";
 //#region src/plugins/env/api.ts
@@ -4040,19 +4041,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);
@@ -4071,14 +4077,20 @@ async function copyContentImages(ctx) {
 		});
 		return 0;
 	}
-	const entries = await readdir(contentDir, { withFileTypes: true });
+	const articleDirectories = await readdir(contentDir, { withFileTypes: true });
 	let copied = 0;
-	for (const entry of entries) {
-		if (!entry.isDirectory()) continue;
-		const source = path.join(contentDir, entry.name, ARTICLE_IMAGE_DIR);
-		if (!existsSync(source)) continue;
-		await cp(source, path.join(ctx.config.outDir, entry.name, ARTICLE_IMAGE_DIR), { recursive: true });
-		copied += 1;
+	for (const article of articleDirectories) {
+		if (!article.isDirectory()) continue;
+		const articleDir = path.join(contentDir, article.name);
+		const assetDirectories = await 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 cp(path.join(articleDir, asset.name), path.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;
@@ -11339,7 +11351,11 @@ function activateEmbed(figure) {
 }
 /**
 * Shared click handler (module-level so mount/unmount detach the same
-* reference): a click on the facade's button activates the embed.
+* 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
@@ -11348,9 +11364,10 @@ function activateEmbed(figure) {
 * ```
 */
 function onFacadeClick(event) {
-	if (!event.target.closest("button.lazy-embed-button")) return;
 	const figure = event.currentTarget;
-	if (figure instanceof HTMLElement) activateEmbed(figure);
+	if (!(figure instanceof HTMLElement)) return;
+	if (figure.dataset.embedActive !== void 0) return;
+	activateEmbed(figure);
 }
 /**
 * Lazy-embed island: facade button click → real `<iframe loading="lazy">`.
@@ -11653,15 +11670,45 @@ 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__ */ jsx("button", {
+		type: "button",
+		class: EMBED_BUTTON_CLASS,
+		"aria-label": `Load embed: ${props.title}`,
+		children: /* @__PURE__ */ 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";
-/** 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.
 *
@@ -11689,83 +11736,162 @@ 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.
+* 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 is embeddable.
+* @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.startsWith("/") && !src.startsWith("//")) return true;
-	return /^https?:\/\//i.test(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;
 }
 /**
-* 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).
+* 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 src - The validated embed URL.
-* @param title - The human-readable embed title (button label, iframe title).
+* @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("https://game.example.com/", "My Game");
+* 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;"` : ""}>${renderToString(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 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>`;
+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`, or carrying a non-embeddable
-* URL, fails the build with the offending value quoted.
+* 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`, or
-* its `src` is not an embeddable URL.
+* @throws {Error} When an `::embed` directive is missing `src` or `title`, its
+* `src` is not embeddable, or its dimensions are invalid.
 * @example
 * ```ts
-* embedTransform(tree);
+* embedTransform(EmbedFacadeButton, tree);
 * ```
 */
-function embedTransform(tree) {
+function embedTransform(facade, 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}").`);
+		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(src, title)
+			value: embedFacadeHtml(facade, {
+				src,
+				title,
+				...dimensions ? {
+					width: dimensions.width,
+					height: dimensions.height
+				} : {},
+				attributes: collectAttributes(node.attributes)
+			}, dimensions)
 		};
 		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
+* 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.
+* `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);
+* unified().use(embedPlugin, { facade: MyFacade });
 * ```
 */
-function embedPlugin() {
-	return embedTransform;
+function embedPlugin(options = {}) {
+	const facade = options.facade ?? EmbedFacadeButton;
+	return (tree) => embedTransform(facade, tree);
 }
 //#endregion
 //#region src/plugins/content/pipeline/mermaid.ts
@@ -12076,7 +12202,7 @@ function defaultRemarkPlugins(config) {
 		remarkDirective,
 		pullQuotePlugin
 	];
-	if (config?.embed) plugins.push(embedPlugin);
+	if (config?.embed) plugins.push([embedPlugin, normalizeEmbedOptions(config.embed)]);
 	if (config?.mermaid) plugins.push([remarkMermaidDiagrams, normalizeMermaidOptions(config.mermaid)]);
 	plugins.push([remarkRehype, { allowDangerousHtml: true }]);
 	return plugins;
@@ -12318,6 +12444,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.
 *
@@ -12348,6 +12476,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.
 *
@@ -12426,7 +12604,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,
@@ -12550,4 +12728,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, lazyEmbed, 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, EmbedFacadeButton, 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.10.0"
+  "version": "1.11.0"
 }