@moku-labs/web 1.10.0 → 1.12.0

package/dist/index.mjs

@@ -5,13 +5,14 @@ import { appendFileSync, existsSync, readFileSync, readdirSync, realpathSync, st
 import { createHash, randomUUID } from "node:crypto";
 import { cp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { homedir, networkInterfaces, tmpdir } from "node:os";
-import path from "node:path";
+import minpath, { default as path } from "node:path";
 import { Feed } from "feed";
 import { h } from "preact";
 import { renderToString } from "preact-render-to-string";
 import { execFileSync } from "node:child_process";
 import { createInterface } from "node:readline";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, fileURLToPath as urlToPath } from "node:url";
+import minproc from "node:process";
 import matter from "gray-matter";
 import rehypeShiki from "@shikijs/rehype";
 import rehypeSanitize from "rehype-sanitize";
@@ -24,6 +25,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
@@ -1569,14 +1571,15 @@ function validateContentConfig(config) {
 }
 /**
 * Validates the `fileSystemContent` provider options (fail-fast at provider
-* 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.
+* construction). Throws when `mermaid`, `embed`, or `gallery` is enabled without
+* `trustedContent: true`: each emits raw HTML (inline SVG / the embed facade /
+* the gallery markup), 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` or `embed` is enabled while `trustedContent` is
-* not `true`.
+* @throws {Error} If `mermaid`, `embed`, or `gallery` is enabled while
+* `trustedContent` is not `true`.
 * @example
 * ```ts
 * validateFileSystemContentOptions({ contentDir: "./content", trustedContent: true, mermaid: true });
@@ -1585,6 +1588,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.");
+	if (Boolean(options.gallery) && options.trustedContent !== true) throw new Error("[web] content: `gallery` requires `trustedContent: true`.\n  Gallery directives render to raw-HTML markup, which the sanitize pass would strip.\n  Set trustedContent: true ONLY for fully author-controlled Markdown.");
 }
 //#endregion
 //#region src/plugins/content/index.ts
@@ -4040,19 +4044,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 +4080,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 +11354,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 +11367,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">`.
@@ -11608,6 +11628,857 @@ function cloudflareBindings() {
 	};
 }
 //#endregion
+//#region node_modules/unist-util-stringify-position/lib/index.js
+/**
+* @typedef {import('unist').Node} Node
+* @typedef {import('unist').Point} Point
+* @typedef {import('unist').Position} Position
+*/
+/**
+* @typedef NodeLike
+* @property {string} type
+* @property {PositionLike | null | undefined} [position]
+*
+* @typedef PointLike
+* @property {number | null | undefined} [line]
+* @property {number | null | undefined} [column]
+* @property {number | null | undefined} [offset]
+*
+* @typedef PositionLike
+* @property {PointLike | null | undefined} [start]
+* @property {PointLike | null | undefined} [end]
+*/
+/**
+* Serialize the positional info of a point, position (start and end points),
+* or node.
+*
+* @param {Node | NodeLike | Point | PointLike | Position | PositionLike | null | undefined} [value]
+*   Node, position, or point.
+* @returns {string}
+*   Pretty printed positional info of a node (`string`).
+*
+*   In the format of a range `ls:cs-le:ce` (when given `node` or `position`)
+*   or a point `l:c` (when given `point`), where `l` stands for line, `c` for
+*   column, `s` for `start`, and `e` for end.
+*   An empty string (`''`) is returned if the given value is neither `node`,
+*   `position`, nor `point`.
+*/
+function stringifyPosition(value) {
+	if (!value || typeof value !== "object") return "";
+	if ("position" in value || "type" in value) return position(value.position);
+	if ("start" in value || "end" in value) return position(value);
+	if ("line" in value || "column" in value) return point(value);
+	return "";
+}
+/**
+* @param {Point | PointLike | null | undefined} point
+* @returns {string}
+*/
+function point(point) {
+	return index(point && point.line) + ":" + index(point && point.column);
+}
+/**
+* @param {Position | PositionLike | null | undefined} pos
+* @returns {string}
+*/
+function position(pos) {
+	return point(pos && pos.start) + "-" + point(pos && pos.end);
+}
+/**
+* @param {number | null | undefined} value
+* @returns {number}
+*/
+function index(value) {
+	return value && typeof value === "number" ? value : 1;
+}
+//#endregion
+//#region node_modules/vfile-message/lib/index.js
+/**
+* @import {Node, Point, Position} from 'unist'
+*/
+/**
+* @typedef {object & {type: string, position?: Position | undefined}} NodeLike
+*
+* @typedef Options
+*   Configuration.
+* @property {Array<Node> | null | undefined} [ancestors]
+*   Stack of (inclusive) ancestor nodes surrounding the message (optional).
+* @property {Error | null | undefined} [cause]
+*   Original error cause of the message (optional).
+* @property {Point | Position | null | undefined} [place]
+*   Place of message (optional).
+* @property {string | null | undefined} [ruleId]
+*   Category of message (optional, example: `'my-rule'`).
+* @property {string | null | undefined} [source]
+*   Namespace of who sent the message (optional, example: `'my-package'`).
+*/
+/**
+* Message.
+*/
+var VFileMessage = class extends Error {
+	/**
+	* Create a message for `reason`.
+	*
+	* > 🪦 **Note**: also has obsolete signatures.
+	*
+	* @overload
+	* @param {string} reason
+	* @param {Options | null | undefined} [options]
+	* @returns
+	*
+	* @overload
+	* @param {string} reason
+	* @param {Node | NodeLike | null | undefined} parent
+	* @param {string | null | undefined} [origin]
+	* @returns
+	*
+	* @overload
+	* @param {string} reason
+	* @param {Point | Position | null | undefined} place
+	* @param {string | null | undefined} [origin]
+	* @returns
+	*
+	* @overload
+	* @param {string} reason
+	* @param {string | null | undefined} [origin]
+	* @returns
+	*
+	* @overload
+	* @param {Error | VFileMessage} cause
+	* @param {Node | NodeLike | null | undefined} parent
+	* @param {string | null | undefined} [origin]
+	* @returns
+	*
+	* @overload
+	* @param {Error | VFileMessage} cause
+	* @param {Point | Position | null | undefined} place
+	* @param {string | null | undefined} [origin]
+	* @returns
+	*
+	* @overload
+	* @param {Error | VFileMessage} cause
+	* @param {string | null | undefined} [origin]
+	* @returns
+	*
+	* @param {Error | VFileMessage | string} causeOrReason
+	*   Reason for message, should use markdown.
+	* @param {Node | NodeLike | Options | Point | Position | string | null | undefined} [optionsOrParentOrPlace]
+	*   Configuration (optional).
+	* @param {string | null | undefined} [origin]
+	*   Place in code where the message originates (example:
+	*   `'my-package:my-rule'` or `'my-rule'`).
+	* @returns
+	*   Instance of `VFileMessage`.
+	*/
+	constructor(causeOrReason, optionsOrParentOrPlace, origin) {
+		super();
+		if (typeof optionsOrParentOrPlace === "string") {
+			origin = optionsOrParentOrPlace;
+			optionsOrParentOrPlace = void 0;
+		}
+		/** @type {string} */
+		let reason = "";
+		/** @type {Options} */
+		let options = {};
+		let legacyCause = false;
+		if (optionsOrParentOrPlace) if ("line" in optionsOrParentOrPlace && "column" in optionsOrParentOrPlace) options = { place: optionsOrParentOrPlace };
+		else if ("start" in optionsOrParentOrPlace && "end" in optionsOrParentOrPlace) options = { place: optionsOrParentOrPlace };
+		else if ("type" in optionsOrParentOrPlace) options = {
+			ancestors: [optionsOrParentOrPlace],
+			place: optionsOrParentOrPlace.position
+		};
+		else options = { ...optionsOrParentOrPlace };
+		if (typeof causeOrReason === "string") reason = causeOrReason;
+		else if (!options.cause && causeOrReason) {
+			legacyCause = true;
+			reason = causeOrReason.message;
+			options.cause = causeOrReason;
+		}
+		if (!options.ruleId && !options.source && typeof origin === "string") {
+			const index = origin.indexOf(":");
+			if (index === -1) options.ruleId = origin;
+			else {
+				options.source = origin.slice(0, index);
+				options.ruleId = origin.slice(index + 1);
+			}
+		}
+		if (!options.place && options.ancestors && options.ancestors) {
+			const parent = options.ancestors[options.ancestors.length - 1];
+			if (parent) options.place = parent.position;
+		}
+		const start = options.place && "start" in options.place ? options.place.start : options.place;
+		/**
+		* Stack of ancestor nodes surrounding the message.
+		*
+		* @type {Array<Node> | undefined}
+		*/
+		this.ancestors = options.ancestors || void 0;
+		/**
+		* Original error cause of the message.
+		*
+		* @type {Error | undefined}
+		*/
+		this.cause = options.cause || void 0;
+		/**
+		* Starting column of message.
+		*
+		* @type {number | undefined}
+		*/
+		this.column = start ? start.column : void 0;
+		/**
+		* State of problem.
+		*
+		* * `true` — error, file not usable
+		* * `false` — warning, change may be needed
+		* * `undefined` — change likely not needed
+		*
+		* @type {boolean | null | undefined}
+		*/
+		this.fatal = void 0;
+		/**
+		* Path of a file (used throughout the `VFile` ecosystem).
+		*
+		* @type {string | undefined}
+		*/
+		this.file = "";
+		/**
+		* Reason for message.
+		*
+		* @type {string}
+		*/
+		this.message = reason;
+		/**
+		* Starting line of error.
+		*
+		* @type {number | undefined}
+		*/
+		this.line = start ? start.line : void 0;
+		/**
+		* Serialized positional info of message.
+		*
+		* On normal errors, this would be something like `ParseError`, buit in
+		* `VFile` messages we use this space to show where an error happened.
+		*/
+		this.name = stringifyPosition(options.place) || "1:1";
+		/**
+		* Place of message.
+		*
+		* @type {Point | Position | undefined}
+		*/
+		this.place = options.place || void 0;
+		/**
+		* Reason for message, should use markdown.
+		*
+		* @type {string}
+		*/
+		this.reason = this.message;
+		/**
+		* Category of message (example: `'my-rule'`).
+		*
+		* @type {string | undefined}
+		*/
+		this.ruleId = options.ruleId || void 0;
+		/**
+		* Namespace of message (example: `'my-package'`).
+		*
+		* @type {string | undefined}
+		*/
+		this.source = options.source || void 0;
+		/**
+		* Stack of message.
+		*
+		* This is used by normal errors to show where something happened in
+		* programming code, irrelevant for `VFile` messages,
+		*
+		* @type {string}
+		*/
+		this.stack = legacyCause && options.cause && typeof options.cause.stack === "string" ? options.cause.stack : "";
+		/**
+		* Specify the source value that’s being reported, which is deemed
+		* incorrect.
+		*
+		* @type {string | undefined}
+		*/
+		this.actual = void 0;
+		/**
+		* Suggest acceptable values that can be used instead of `actual`.
+		*
+		* @type {Array<string> | undefined}
+		*/
+		this.expected = void 0;
+		/**
+		* Long form description of the message (you should use markdown).
+		*
+		* @type {string | undefined}
+		*/
+		this.note = void 0;
+		/**
+		* Link to docs for the message.
+		*
+		* > 👉 **Note**: this must be an absolute URL that can be passed as `x`
+		* > to `new URL(x)`.
+		*
+		* @type {string | undefined}
+		*/
+		this.url = void 0;
+	}
+};
+VFileMessage.prototype.file = "";
+VFileMessage.prototype.name = "";
+VFileMessage.prototype.reason = "";
+VFileMessage.prototype.message = "";
+VFileMessage.prototype.stack = "";
+VFileMessage.prototype.column = void 0;
+VFileMessage.prototype.line = void 0;
+VFileMessage.prototype.ancestors = void 0;
+VFileMessage.prototype.cause = void 0;
+VFileMessage.prototype.fatal = void 0;
+VFileMessage.prototype.place = void 0;
+VFileMessage.prototype.ruleId = void 0;
+VFileMessage.prototype.source = void 0;
+//#endregion
+//#region node_modules/vfile/lib/minurl.shared.js
+/**
+* Checks if a value has the shape of a WHATWG URL object.
+*
+* Using a symbol or instanceof would not be able to recognize URL objects
+* coming from other implementations (e.g. in Electron), so instead we are
+* checking some well known properties for a lack of a better test.
+*
+* We use `href` and `protocol` as they are the only properties that are
+* easy to retrieve and calculate due to the lazy nature of the getters.
+*
+* We check for auth attribute to distinguish legacy url instance with
+* WHATWG URL instance.
+*
+* @param {unknown} fileUrlOrPath
+*   File path or URL.
+* @returns {fileUrlOrPath is URL}
+*   Whether it’s a URL.
+*/
+function isUrl(fileUrlOrPath) {
+	return Boolean(fileUrlOrPath !== null && typeof fileUrlOrPath === "object" && "href" in fileUrlOrPath && fileUrlOrPath.href && "protocol" in fileUrlOrPath && fileUrlOrPath.protocol && fileUrlOrPath.auth === void 0);
+}
+//#endregion
+//#region node_modules/vfile/lib/index.js
+/**
+* @import {Node, Point, Position} from 'unist'
+* @import {Options as MessageOptions} from 'vfile-message'
+* @import {Compatible, Data, Map, Options, Value} from 'vfile'
+*/
+/**
+* @typedef {object & {type: string, position?: Position | undefined}} NodeLike
+*/
+/**
+* Order of setting (least specific to most), we need this because otherwise
+* `{stem: 'a', path: '~/b.js'}` would throw, as a path is needed before a
+* stem can be set.
+*/
+const order = [
+	"history",
+	"path",
+	"basename",
+	"stem",
+	"extname",
+	"dirname"
+];
+var VFile = class {
+	/**
+	* Create a new virtual file.
+	*
+	* `options` is treated as:
+	*
+	* *   `string` or `Uint8Array` — `{value: options}`
+	* *   `URL` — `{path: options}`
+	* *   `VFile` — shallow copies its data over to the new file
+	* *   `object` — all fields are shallow copied over to the new file
+	*
+	* Path related fields are set in the following order (least specific to
+	* most specific): `history`, `path`, `basename`, `stem`, `extname`,
+	* `dirname`.
+	*
+	* You cannot set `dirname` or `extname` without setting either `history`,
+	* `path`, `basename`, or `stem` too.
+	*
+	* @param {Compatible | null | undefined} [value]
+	*   File value.
+	* @returns
+	*   New instance.
+	*/
+	constructor(value) {
+		/** @type {Options | VFile} */
+		let options;
+		if (!value) options = {};
+		else if (isUrl(value)) options = { path: value };
+		else if (typeof value === "string" || isUint8Array(value)) options = { value };
+		else options = value;
+		/**
+		* Base of `path` (default: `process.cwd()` or `'/'` in browsers).
+		*
+		* @type {string}
+		*/
+		this.cwd = "cwd" in options ? "" : minproc.cwd();
+		/**
+		* Place to store custom info (default: `{}`).
+		*
+		* It’s OK to store custom data directly on the file but moving it to
+		* `data` is recommended.
+		*
+		* @type {Data}
+		*/
+		this.data = {};
+		/**
+		* List of file paths the file moved between.
+		*
+		* The first is the original path and the last is the current path.
+		*
+		* @type {Array<string>}
+		*/
+		this.history = [];
+		/**
+		* List of messages associated with the file.
+		*
+		* @type {Array<VFileMessage>}
+		*/
+		this.messages = [];
+		/**
+		* Raw value.
+		*
+		* @type {Value}
+		*/
+		this.value;
+		/**
+		* Source map.
+		*
+		* This type is equivalent to the `RawSourceMap` type from the `source-map`
+		* module.
+		*
+		* @type {Map | null | undefined}
+		*/
+		this.map;
+		/**
+		* Custom, non-string, compiled, representation.
+		*
+		* This is used by unified to store non-string results.
+		* One example is when turning markdown into React nodes.
+		*
+		* @type {unknown}
+		*/
+		this.result;
+		/**
+		* Whether a file was saved to disk.
+		*
+		* This is used by vfile reporters.
+		*
+		* @type {boolean}
+		*/
+		this.stored;
+		let index = -1;
+		while (++index < order.length) {
+			const field = order[index];
+			if (field in options && options[field] !== void 0 && options[field] !== null) this[field] = field === "history" ? [...options[field]] : options[field];
+		}
+		/** @type {string} */
+		let field;
+		for (field in options) if (!order.includes(field)) this[field] = options[field];
+	}
+	/**
+	* Get the basename (including extname) (example: `'index.min.js'`).
+	*
+	* @returns {string | undefined}
+	*   Basename.
+	*/
+	get basename() {
+		return typeof this.path === "string" ? minpath.basename(this.path) : void 0;
+	}
+	/**
+	* Set basename (including extname) (`'index.min.js'`).
+	*
+	* Cannot contain path separators (`'/'` on unix, macOS, and browsers, `'\'`
+	* on windows).
+	* Cannot be nullified (use `file.path = file.dirname` instead).
+	*
+	* @param {string} basename
+	*   Basename.
+	* @returns {undefined}
+	*   Nothing.
+	*/
+	set basename(basename) {
+		assertNonEmpty(basename, "basename");
+		assertPart(basename, "basename");
+		this.path = minpath.join(this.dirname || "", basename);
+	}
+	/**
+	* Get the parent path (example: `'~'`).
+	*
+	* @returns {string | undefined}
+	*   Dirname.
+	*/
+	get dirname() {
+		return typeof this.path === "string" ? minpath.dirname(this.path) : void 0;
+	}
+	/**
+	* Set the parent path (example: `'~'`).
+	*
+	* Cannot be set if there’s no `path` yet.
+	*
+	* @param {string | undefined} dirname
+	*   Dirname.
+	* @returns {undefined}
+	*   Nothing.
+	*/
+	set dirname(dirname) {
+		assertPath(this.basename, "dirname");
+		this.path = minpath.join(dirname || "", this.basename);
+	}
+	/**
+	* Get the extname (including dot) (example: `'.js'`).
+	*
+	* @returns {string | undefined}
+	*   Extname.
+	*/
+	get extname() {
+		return typeof this.path === "string" ? minpath.extname(this.path) : void 0;
+	}
+	/**
+	* Set the extname (including dot) (example: `'.js'`).
+	*
+	* Cannot contain path separators (`'/'` on unix, macOS, and browsers, `'\'`
+	* on windows).
+	* Cannot be set if there’s no `path` yet.
+	*
+	* @param {string | undefined} extname
+	*   Extname.
+	* @returns {undefined}
+	*   Nothing.
+	*/
+	set extname(extname) {
+		assertPart(extname, "extname");
+		assertPath(this.dirname, "extname");
+		if (extname) {
+			if (extname.codePointAt(0) !== 46) throw new Error("`extname` must start with `.`");
+			if (extname.includes(".", 1)) throw new Error("`extname` cannot contain multiple dots");
+		}
+		this.path = minpath.join(this.dirname, this.stem + (extname || ""));
+	}
+	/**
+	* Get the full path (example: `'~/index.min.js'`).
+	*
+	* @returns {string}
+	*   Path.
+	*/
+	get path() {
+		return this.history[this.history.length - 1];
+	}
+	/**
+	* Set the full path (example: `'~/index.min.js'`).
+	*
+	* Cannot be nullified.
+	* You can set a file URL (a `URL` object with a `file:` protocol) which will
+	* be turned into a path with `url.fileURLToPath`.
+	*
+	* @param {URL | string} path
+	*   Path.
+	* @returns {undefined}
+	*   Nothing.
+	*/
+	set path(path) {
+		if (isUrl(path)) path = urlToPath(path);
+		assertNonEmpty(path, "path");
+		if (this.path !== path) this.history.push(path);
+	}
+	/**
+	* Get the stem (basename w/o extname) (example: `'index.min'`).
+	*
+	* @returns {string | undefined}
+	*   Stem.
+	*/
+	get stem() {
+		return typeof this.path === "string" ? minpath.basename(this.path, this.extname) : void 0;
+	}
+	/**
+	* Set the stem (basename w/o extname) (example: `'index.min'`).
+	*
+	* Cannot contain path separators (`'/'` on unix, macOS, and browsers, `'\'`
+	* on windows).
+	* Cannot be nullified (use `file.path = file.dirname` instead).
+	*
+	* @param {string} stem
+	*   Stem.
+	* @returns {undefined}
+	*   Nothing.
+	*/
+	set stem(stem) {
+		assertNonEmpty(stem, "stem");
+		assertPart(stem, "stem");
+		this.path = minpath.join(this.dirname || "", stem + (this.extname || ""));
+	}
+	/**
+	* Create a fatal message for `reason` associated with the file.
+	*
+	* The `fatal` field of the message is set to `true` (error; file not usable)
+	* and the `file` field is set to the current file path.
+	* The message is added to the `messages` field on `file`.
+	*
+	* > 🪦 **Note**: also has obsolete signatures.
+	*
+	* @overload
+	* @param {string} reason
+	* @param {MessageOptions | null | undefined} [options]
+	* @returns {never}
+	*
+	* @overload
+	* @param {string} reason
+	* @param {Node | NodeLike | null | undefined} parent
+	* @param {string | null | undefined} [origin]
+	* @returns {never}
+	*
+	* @overload
+	* @param {string} reason
+	* @param {Point | Position | null | undefined} place
+	* @param {string | null | undefined} [origin]
+	* @returns {never}
+	*
+	* @overload
+	* @param {string} reason
+	* @param {string | null | undefined} [origin]
+	* @returns {never}
+	*
+	* @overload
+	* @param {Error | VFileMessage} cause
+	* @param {Node | NodeLike | null | undefined} parent
+	* @param {string | null | undefined} [origin]
+	* @returns {never}
+	*
+	* @overload
+	* @param {Error | VFileMessage} cause
+	* @param {Point | Position | null | undefined} place
+	* @param {string | null | undefined} [origin]
+	* @returns {never}
+	*
+	* @overload
+	* @param {Error | VFileMessage} cause
+	* @param {string | null | undefined} [origin]
+	* @returns {never}
+	*
+	* @param {Error | VFileMessage | string} causeOrReason
+	*   Reason for message, should use markdown.
+	* @param {Node | NodeLike | MessageOptions | Point | Position | string | null | undefined} [optionsOrParentOrPlace]
+	*   Configuration (optional).
+	* @param {string | null | undefined} [origin]
+	*   Place in code where the message originates (example:
+	*   `'my-package:my-rule'` or `'my-rule'`).
+	* @returns {never}
+	*   Never.
+	* @throws {VFileMessage}
+	*   Message.
+	*/
+	fail(causeOrReason, optionsOrParentOrPlace, origin) {
+		const message = this.message(causeOrReason, optionsOrParentOrPlace, origin);
+		message.fatal = true;
+		throw message;
+	}
+	/**
+	* Create an info message for `reason` associated with the file.
+	*
+	* The `fatal` field of the message is set to `undefined` (info; change
+	* likely not needed) and the `file` field is set to the current file path.
+	* The message is added to the `messages` field on `file`.
+	*
+	* > 🪦 **Note**: also has obsolete signatures.
+	*
+	* @overload
+	* @param {string} reason
+	* @param {MessageOptions | null | undefined} [options]
+	* @returns {VFileMessage}
+	*
+	* @overload
+	* @param {string} reason
+	* @param {Node | NodeLike | null | undefined} parent
+	* @param {string | null | undefined} [origin]
+	* @returns {VFileMessage}
+	*
+	* @overload
+	* @param {string} reason
+	* @param {Point | Position | null | undefined} place
+	* @param {string | null | undefined} [origin]
+	* @returns {VFileMessage}
+	*
+	* @overload
+	* @param {string} reason
+	* @param {string | null | undefined} [origin]
+	* @returns {VFileMessage}
+	*
+	* @overload
+	* @param {Error | VFileMessage} cause
+	* @param {Node | NodeLike | null | undefined} parent
+	* @param {string | null | undefined} [origin]
+	* @returns {VFileMessage}
+	*
+	* @overload
+	* @param {Error | VFileMessage} cause
+	* @param {Point | Position | null | undefined} place
+	* @param {string | null | undefined} [origin]
+	* @returns {VFileMessage}
+	*
+	* @overload
+	* @param {Error | VFileMessage} cause
+	* @param {string | null | undefined} [origin]
+	* @returns {VFileMessage}
+	*
+	* @param {Error | VFileMessage | string} causeOrReason
+	*   Reason for message, should use markdown.
+	* @param {Node | NodeLike | MessageOptions | Point | Position | string | null | undefined} [optionsOrParentOrPlace]
+	*   Configuration (optional).
+	* @param {string | null | undefined} [origin]
+	*   Place in code where the message originates (example:
+	*   `'my-package:my-rule'` or `'my-rule'`).
+	* @returns {VFileMessage}
+	*   Message.
+	*/
+	info(causeOrReason, optionsOrParentOrPlace, origin) {
+		const message = this.message(causeOrReason, optionsOrParentOrPlace, origin);
+		message.fatal = void 0;
+		return message;
+	}
+	/**
+	* Create a message for `reason` associated with the file.
+	*
+	* The `fatal` field of the message is set to `false` (warning; change may be
+	* needed) and the `file` field is set to the current file path.
+	* The message is added to the `messages` field on `file`.
+	*
+	* > 🪦 **Note**: also has obsolete signatures.
+	*
+	* @overload
+	* @param {string} reason
+	* @param {MessageOptions | null | undefined} [options]
+	* @returns {VFileMessage}
+	*
+	* @overload
+	* @param {string} reason
+	* @param {Node | NodeLike | null | undefined} parent
+	* @param {string | null | undefined} [origin]
+	* @returns {VFileMessage}
+	*
+	* @overload
+	* @param {string} reason
+	* @param {Point | Position | null | undefined} place
+	* @param {string | null | undefined} [origin]
+	* @returns {VFileMessage}
+	*
+	* @overload
+	* @param {string} reason
+	* @param {string | null | undefined} [origin]
+	* @returns {VFileMessage}
+	*
+	* @overload
+	* @param {Error | VFileMessage} cause
+	* @param {Node | NodeLike | null | undefined} parent
+	* @param {string | null | undefined} [origin]
+	* @returns {VFileMessage}
+	*
+	* @overload
+	* @param {Error | VFileMessage} cause
+	* @param {Point | Position | null | undefined} place
+	* @param {string | null | undefined} [origin]
+	* @returns {VFileMessage}
+	*
+	* @overload
+	* @param {Error | VFileMessage} cause
+	* @param {string | null | undefined} [origin]
+	* @returns {VFileMessage}
+	*
+	* @param {Error | VFileMessage | string} causeOrReason
+	*   Reason for message, should use markdown.
+	* @param {Node | NodeLike | MessageOptions | Point | Position | string | null | undefined} [optionsOrParentOrPlace]
+	*   Configuration (optional).
+	* @param {string | null | undefined} [origin]
+	*   Place in code where the message originates (example:
+	*   `'my-package:my-rule'` or `'my-rule'`).
+	* @returns {VFileMessage}
+	*   Message.
+	*/
+	message(causeOrReason, optionsOrParentOrPlace, origin) {
+		const message = new VFileMessage(causeOrReason, optionsOrParentOrPlace, origin);
+		if (this.path) {
+			message.name = this.path + ":" + message.name;
+			message.file = this.path;
+		}
+		message.fatal = false;
+		this.messages.push(message);
+		return message;
+	}
+	/**
+	* Serialize the file.
+	*
+	* > **Note**: which encodings are supported depends on the engine.
+	* > For info on Node.js, see:
+	* > <https://nodejs.org/api/util.html#whatwg-supported-encodings>.
+	*
+	* @param {string | null | undefined} [encoding='utf8']
+	*   Character encoding to understand `value` as when it’s a `Uint8Array`
+	*   (default: `'utf-8'`).
+	* @returns {string}
+	*   Serialized file.
+	*/
+	toString(encoding) {
+		if (this.value === void 0) return "";
+		if (typeof this.value === "string") return this.value;
+		return new TextDecoder(encoding || void 0).decode(this.value);
+	}
+};
+/**
+* Assert that `part` is not a path (as in, does not contain `path.sep`).
+*
+* @param {string | null | undefined} part
+*   File path part.
+* @param {string} name
+*   Part name.
+* @returns {undefined}
+*   Nothing.
+*/
+function assertPart(part, name) {
+	if (part && part.includes(minpath.sep)) throw new Error("`" + name + "` cannot be a path: did not expect `" + minpath.sep + "`");
+}
+/**
+* Assert that `part` is not empty.
+*
+* @param {string | undefined} part
+*   Thing.
+* @param {string} name
+*   Part name.
+* @returns {asserts part is string}
+*   Nothing.
+*/
+function assertNonEmpty(part, name) {
+	if (!part) throw new Error("`" + name + "` cannot be empty");
+}
+/**
+* Assert `path` exists.
+*
+* @param {string | undefined} path
+*   Path.
+* @param {string} name
+*   Dependency name.
+* @returns {asserts path is string}
+*   Nothing.
+*/
+function assertPath(path, name) {
+	if (!path) throw new Error("Setting `" + name + "` requires `path` to be set too");
+}
+/**
+* Assert `value` is an `Uint8Array`.
+*
+* @param {unknown} value
+*   thing.
+* @returns {value is Uint8Array}
+*   Whether `value` is an `Uint8Array`.
+*/
+function isUint8Array(value) {
+	return Boolean(value && typeof value === "object" && "byteLength" in value && "byteOffset" in value);
+}
+//#endregion
 //#region src/plugins/content/pipeline/frontmatter.ts
 /**
 * @file content pipeline — frontmatter parsing.
@@ -11653,15 +12524,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 +12590,402 @@ 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$1(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(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 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 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$1(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/gallery-default.tsx
+/** CSS class on the gallery's slide track. */
+const GALLERY_TRACK_CLASS = "gallery-track";
+/**
+* Default `::gallery` inner content: a single track holding every slide `<img>`
+* in folder order. A companion gallery island (consumer-provided) can enhance
+* the track with swipe/keyboard/lightbox; with no island and no CSS it is still
+* a plain horizontally-scrollable image strip. Provided as the default and as a
+* composable building block for custom galleries.
+*
+* @param props - The gallery props (the resolved `slides`).
+* @returns The gallery inner-content VNode.
+* @example
+* ```tsx
+* // Compose the default inside a richer custom gallery:
+* const MyGallery = (p: GalleryProps) => (
+*   <figure><GalleryTrack {...p} /><figcaption>{p.caption}</figcaption></figure>
+* );
+* ```
+*/
+function GalleryTrack(props) {
+	return /* @__PURE__ */ jsx("div", {
+		class: GALLERY_TRACK_CLASS,
+		"data-gallery-track": true,
+		children: props.slides.map((slide) => /* @__PURE__ */ jsx("img", {
+			src: slide.src,
+			alt: slide.alt
+		}, slide.src))
+	});
+}
+//#endregion
+//#region src/plugins/content/pipeline/gallery.ts
+/**
+* @file content pipeline — `::gallery` folder galleries.
+*
+* Rewrites `::gallery{src="./images/dir/" caption="…"}` leaf directives into a
+* static swipeable image set at the mdast stage (BEFORE the remark-rehype bridge):
+* a framework-owned `<div class="gallery" data-component="gallery">` carrying the
+* island hook, wrapping inner content rendered (at build time, to static markup)
+* by a Preact component — the built-in {@link GalleryTrack} by default, or a
+* consumer component via `gallery.component`.
+*
+* Unlike `::embed` (one src resolved later by the provider), a gallery's `src` is a
+* co-located FOLDER that must be listed at build time, which needs the article's
+* source path. The provider supplies the article `slug` via the VFile `data`
+* (providers.ts), and the `contentDir` is bound at pipeline-build time — so this
+* transform reads `<contentDir>/<slug>/<src>` from disk, sorts its images, and
+* resolves each to its shared `/<slug>/<dir>/<file>` URL (identical from every
+* locale page, mirroring co-located images). The companion gallery SPA island
+* (consumer-provided) wires swipe/keyboard/lightbox on `[data-component="gallery"]`.
+*/
+/** CSS class on the `<div>` wrapping each gallery. */
+const GALLERY_WRAPPER_CLASS = "gallery";
+/** `data-component` name binding the gallery to its SPA island. */
+const GALLERY_COMPONENT_NAME = "gallery";
+/** Image file extensions a gallery folder expands over. */
+const IMAGE_EXTENSIONS = new Set([
+	".webp",
+	".jpg",
+	".jpeg",
+	".png",
+	".gif",
+	".avif"
+]);
+/**
+* Type guard for a `::gallery` leaf directive.
+*
+* @param node - AST node to test.
+* @returns `true` when the node is a `::gallery` leaf directive.
+* @example
+* ```ts
+* if (isGalleryDirective(node)) console.log(node.attributes?.src);
+* ```
+*/
+function isGalleryDirective(node) {
+	return node.type === "leafDirective" && node.name === "gallery";
+}
+/**
+* Resolve `.`/`..` segments of a path built from `slug/src/file` into the single
+* shared absolute URL the content-assets build phase copies the folder to.
+*
+* @param slug - Article directory name.
+* @param src - The directive `src` (co-located relative folder, e.g. `./images/dir/`).
+* @param file - One image file name inside the folder.
+* @returns The shared absolute slide URL (`/<slug>/<dir>/<file>`).
+* @example
+* ```ts
+* slideUrl("post", "./images/mk/", "a.webp"); // "/post/images/mk/a.webp"
+* ```
+*/
+function slideUrl(slug, src, file) {
+	const resolved = [];
+	for (const segment of `${slug}/${src}/${file}`.split("/")) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") resolved.pop();
+		else resolved.push(segment);
+	}
+	return `/${resolved.join("/")}`;
+}
+/**
+* Read a gallery folder from disk and build its sorted slide list. Each slide
+* gets the directive `caption` plus a ` · N` index suffix as alt (or just `N`).
+*
+* @param contentDir - The provider's content directory.
+* @param slug - Article directory name (from the VFile data).
+* @param src - The directive `src` (co-located relative folder).
+* @param caption - The directive `caption` attribute (may be empty).
+* @returns The sorted slides.
+* @throws {Error} When the folder is missing or holds no images.
+* @example
+* ```ts
+* resolveSlides("./content", "post", "./images/mk/", "Our game");
+* ```
+*/
+function resolveSlides(contentDir, slug, src, caption) {
+	const folder = path.join(contentDir, slug, src);
+	let entries;
+	try {
+		entries = readdirSync(folder);
+	} catch {
+		throw new Error(`[web] content: \`::gallery\` folder not found: "${src}" (looked in ${folder}).`);
+	}
+	const files = entries.filter((name) => IMAGE_EXTENSIONS.has(path.extname(name).toLowerCase())).toSorted((a, b) => a.localeCompare(b, "en"));
+	if (files.length === 0) throw new Error(`[web] content: \`::gallery\` folder has no images: "${src}" (${folder}).`);
+	return files.map((file, index) => ({
+		src: slideUrl(slug, src, file),
+		alt: caption ? `${caption} · ${index + 1}` : `${index + 1}`
+	}));
+}
+/**
+* Collect the directive's raw attribute bag into a plain string record, dropping
+* `null`/`undefined` values (so a custom component can read arbitrary extra options).
+*
+* @param attributes - The raw directive attributes (or undefined).
+* @returns A string-valued attribute record.
+* @example
+* ```ts
+* collectAttributes({ src: "x", layout: "dots", flag: null }); // { src: "x", layout: "dots" }
+* ```
+*/
+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 gallery HTML for one directive: the framework-owned `<div>`
+* (island hook in `data-component`) wrapping the component's inner content, SSR'd
+* to static markup.
+*
+* @param component - The gallery component (default {@link GalleryTrack}).
+* @param slides - The resolved slides.
+* @param caption - The directive `caption` attribute.
+* @param attributes - The raw directive attribute bag.
+* @returns The gallery HTML string.
+* @example
+* ```ts
+* galleryHtml(GalleryTrack, slides, "Our game", { src: "./images/mk/" });
+* ```
+*/
+function galleryHtml(component, slides, caption, attributes) {
+	return `<div class="${GALLERY_WRAPPER_CLASS}" data-component="${GALLERY_COMPONENT_NAME}">${renderToString(h(component, {
+		slides,
+		caption,
+		attributes
+	}))}</div>`;
+}
+/**
+* Mdast transformer rewriting every `::gallery` leaf directive to its gallery
+* HTML node. A directive missing `src`, or pointing at a missing/empty folder,
+* fails the build with the offending value quoted. Skipped entirely when the
+* VFile carries no `slug` (the standalone `render()` path has no article context).
+*
+* @param options - Resolved transform options (component + contentDir).
+* @param tree - The mdast tree to mutate.
+* @param file - The VFile (its `data.slug` locates the article on disk).
+* @throws {Error} When a `::gallery` directive is missing `src`, or its folder is
+* missing/empty.
+* @example
+* ```ts
+* galleryTransform({ component: GalleryTrack, contentDir: "./content" }, tree, file);
+* ```
+*/
+function galleryTransform(options, tree, file) {
+	const slug = typeof file.data.slug === "string" ? file.data.slug : void 0;
+	const component = options.component ?? GalleryTrack;
+	visit(tree, (node, index, parent) => {
+		if (!isGalleryDirective(node)) return;
+		if (parent === void 0 || index === void 0) return;
+		if (slug === void 0) return;
+		const src = node.attributes?.src ?? "";
+		if (src === "") throw new Error("[web] content: `::gallery` requires a `src` folder, e.g. ::gallery{src=\"./images/dir/\"}.");
+		const caption = node.attributes?.caption ?? "";
+		const html = {
+			type: "html",
+			value: galleryHtml(component, resolveSlides(options.contentDir, slug, src, caption), caption, collectAttributes(node.attributes))
+		};
+		parent.children[index] = html;
+	});
+}
+/**
+* Normalize the provider's `gallery` config value (`boolean | options`) plus the
+* provider `contentDir` into the resolved {@link GalleryTransformOptions} the
+* transform factory needs.
+*
+* @param gallery - The raw `FileSystemContentOptions.gallery` value (truthy).
+* @param contentDir - The provider's content directory.
+* @returns The resolved transform options.
+* @example
+* ```ts
+* normalizeGalleryOptions(true, "./content"); // { contentDir: "./content" }
+* normalizeGalleryOptions({ component: MyGallery }, "./content");
+* ```
+*/
+function normalizeGalleryOptions(gallery, contentDir) {
+	return typeof gallery === "boolean" ? { contentDir } : {
+		...gallery,
+		contentDir
+	};
+}
+/**
+* Remark transform factory: rewrites `::gallery{src="…"}` leaf directives into
+* static swipeable galleries (see the file header). Opt-in via the provider's
+* `gallery` option; requires `trustedContent: true` because the markup is raw HTML
+* the sanitize pass would strip. The inner content is rendered by
+* `options.component` (a consumer Preact component) or the built-in
+* {@link GalleryTrack}; folders are read from `options.contentDir` against the
+* per-article `slug` on the VFile.
+*
+* @param options - Resolved transform options (component + contentDir).
+* @returns An mdast tree transformer.
+* @example
+* ```ts
+* unified().use(galleryPlugin, { component: MyGallery, contentDir: "./content" });
+* ```
+*/
+function galleryPlugin(options) {
+	return (tree, file) => galleryTransform(options, tree, file);
 }
 //#endregion
 //#region src/plugins/content/pipeline/mermaid.ts
@@ -12076,7 +13296,8 @@ function defaultRemarkPlugins(config) {
 		remarkDirective,
 		pullQuotePlugin
 	];
-	if (config?.embed) plugins.push(embedPlugin);
+	if (config?.embed) plugins.push([embedPlugin, normalizeEmbedOptions(config.embed)]);
+	if (config?.gallery) plugins.push([galleryPlugin, normalizeGalleryOptions(config.gallery, config.contentDir)]);
 	if (config?.mermaid) plugins.push([remarkMermaidDiagrams, normalizeMermaidOptions(config.mermaid)]);
 	plugins.push([remarkRehype, { allowDangerousHtml: true }]);
 	return plugins;
@@ -12318,6 +13539,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 +13571,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 +13699,10 @@ 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(new VFile({
+				value: body,
+				data: { slug }
+			}))), slug), slug);
 			const { readingTime, wordCount } = calculateReadingTime(body);
 			return {
 				frontmatter,
@@ -12550,4 +13826,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, GalleryTrack, 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 };