@moku-labs/web 1.11.0 → 1.12.1

package/dist/index.cjs

@@ -40,6 +40,7 @@ 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);
+let node_process = require("node:process");
 //#region src/plugins/env/api.ts
 /** Error prefix for all env API failures. */
 const ERROR_PREFIX$16 = "[web]";
@@ -1583,14 +1584,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 });
@@ -1599,6 +1601,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
@@ -10636,6 +10639,17 @@ async function performNavigation(pathname, handlers, signal) {
 	}
 }
 /**
+* Whether the user has asked the platform to minimise motion.
+*
+* @returns `true` when `(prefers-reduced-motion: reduce)` currently matches; `false` when
+*   it does not, or when `matchMedia` is absent (guards SSR/test environments).
+* @example
+* const behavior: ScrollBehavior = prefersReducedMotion() ? "instant" : "smooth";
+*/
+function prefersReducedMotion() {
+	return typeof globalThis.matchMedia === "function" && globalThis.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+/**
 * Run a DOM-mutating swap, optionally wrapped in the View Transitions API when
 * enabled and supported (instant swap otherwise — never throws).
 *
@@ -10656,7 +10670,7 @@ async function performNavigation(pathname, handlers, signal) {
 * runSwap(() => current.replaceWith(next), true, () => scrollTo({ top: 0, behavior: "instant" }));
 */
 function runSwap(doSwap, viewTransitions, beforeCapture) {
-	const reduced = typeof globalThis.matchMedia === "function" && globalThis.matchMedia("(prefers-reduced-motion: reduce)").matches;
+	const reduced = prefersReducedMotion();
 	const docWithVt = document;
 	const canUseViewTransitions = viewTransitions && !reduced && typeof docWithVt.startViewTransition === "function";
 	beforeCapture?.();
@@ -10754,7 +10768,7 @@ function attachHistoryFallback(handlers, navigate = (pathname, _scrollToTop, sig
 		if (pathWithSearch(url) === pathWithSearch(location)) {
 			window.scrollTo({
 				top: 0,
-				behavior: "smooth"
+				behavior: prefersReducedMotion() ? "instant" : "smooth"
 			});
 			return;
 		}
@@ -10808,7 +10822,7 @@ function attachNavigationApi(navigation, handlers, navigate = (pathname, _scroll
 			navEvent.intercept({ handler: () => {
 				window.scrollTo({
 					top: 0,
-					behavior: "smooth"
+					behavior: prefersReducedMotion() ? "instant" : "smooth"
 				});
 				return Promise.resolve();
 			} });
@@ -10985,26 +10999,30 @@ function createSpaKernel(state, config, emit, deps) {
 	let pendingScrollToTop = true;
 	/**
 	* Apply the in-flight navigation's scroll intent — the swap's `beforeCapture` hook.
-	* For a forward nav it scrolls to top BEFORE the snapshot is captured, so the old and
-	* new states share scrollY=0 (no delta → the sticky header never un-pins) and there is
-	* no pre-fetch scroll pause. Traverse (back/forward) sets `pendingScrollToTop = false`
-	* and restores its saved position after the swap instead.
+	* For a forward nav it scrolls to top BEFORE the swap (and, with view transitions on,
+	* before the "old" snapshot is captured), so the old and new states share scrollY=0:
+	* no delta for a transition to animate → a `position: sticky` header never un-pins.
+	* Traverse (back/forward) sets `pendingScrollToTop = false` and restores its saved
+	* position after the swap instead.
 	*
-	* Scroll behaviour: `"instant"` ONLY when view transitions are enabled — that is what
-	* keeps scrollY=0 in the captured snapshot (a `scroll-behavior: smooth` would otherwise
-	* animate the reset and re-create the delta → sticky-header flicker). With view
-	* transitions OFF there is no snapshot to protect, so it honours the page's
-	* `scroll-behavior` (`"auto"` = use the CSS value, e.g. a smooth scroll-to-top on nav).
+	* The reset is ALWAYS `"instant"`, never the CSS-driven `"auto"`. It runs synchronously
+	* immediately before the swap, and the swap mutates document height (the outgoing page is
+	* usually taller than the incoming one). A smooth scroll — from `behavior: "smooth"` or a
+	* page `scroll-behavior: smooth` that `"auto"` would inherit — is still animating when that
+	* height change lands; the browser clamps scrollY to the new, smaller maximum and cancels
+	* the in-flight animation there (worst on WebKit), stranding the page near the OLD position
+	* instead of the top. Instant lands scrollY=0 before the swap, every time. (A smooth
+	* scroll-to-top on the SAME page is unaffected — the router's same-page handler animates
+	* it, where there is no swap to race.)
 	*
 	* @example
 	* runSwap(renderAndMount, viewTransitions, applyPendingScroll);
 	*/
 	const applyPendingScroll = () => {
 		if (!pendingScrollToTop) return;
-		const behavior = resolved.viewTransitions ? "instant" : "auto";
 		window.scrollTo({
 			top: 0,
-			behavior
+			behavior: "instant"
 		});
 	};
 	/**
@@ -11638,6 +11656,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 ? "" : node_process.default.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" ? node_path$1.default.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 = node_path$1.default.join(this.dirname || "", basename);
+	}
+	/**
+	* Get the parent path (example: `'~'`).
+	*
+	* @returns {string | undefined}
+	*   Dirname.
+	*/
+	get dirname() {
+		return typeof this.path === "string" ? node_path$1.default.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 = node_path$1.default.join(dirname || "", this.basename);
+	}
+	/**
+	* Get the extname (including dot) (example: `'.js'`).
+	*
+	* @returns {string | undefined}
+	*   Extname.
+	*/
+	get extname() {
+		return typeof this.path === "string" ? node_path$1.default.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 = node_path$1.default.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 = (0, node_url.fileURLToPath)(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" ? node_path$1.default.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 = node_path$1.default.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(node_path$1.default.sep)) throw new Error("`" + name + "` cannot be a path: did not expect `" + node_path$1.default.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.
@@ -11808,7 +12677,7 @@ function parseDimensions(width, height) {
 * collectAttributes({ src: "x", poster: "/p.jpg", flag: null }); // { src: "x", poster: "/p.jpg" }
 * ```
 */
-function collectAttributes(attributes) {
+function collectAttributes$1(attributes) {
 	const out = {};
 	for (const [key, value] of Object.entries(attributes ?? {})) if (typeof value === "string") out[key] = value;
 	return out;
@@ -11881,7 +12750,7 @@ function embedTransform(facade, tree) {
 					width: dimensions.width,
 					height: dimensions.height
 				} : {},
-				attributes: collectAttributes(node.attributes)
+				attributes: collectAttributes$1(node.attributes)
 			}, dimensions)
 		};
 		parent.children[index] = html;
@@ -11907,6 +12776,246 @@ function embedPlugin(options = {}) {
 	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__ */ (0, preact_jsx_runtime.jsx)("div", {
+		class: GALLERY_TRACK_CLASS,
+		"data-gallery-track": true,
+		children: props.slides.map((slide) => /* @__PURE__ */ (0, preact_jsx_runtime.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 = node_path$1.default.join(contentDir, slug, src);
+	let entries;
+	try {
+		entries = (0, node_fs.readdirSync)(folder);
+	} catch {
+		throw new Error(`[web] content: \`::gallery\` folder not found: "${src}" (looked in ${folder}).`);
+	}
+	const files = entries.filter((name) => IMAGE_EXTENSIONS.has(node_path$1.default.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}">${(0, preact_render_to_string.renderToString)((0, preact.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;
+	(0, unist_util_visit.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
 /** CSS class on the `<figure>` wrapper around each rendered diagram. */
 const MERMAID_FIGURE_CLASS = "mermaid-diagram";
@@ -12216,6 +13325,7 @@ function defaultRemarkPlugins(config) {
 		pullQuotePlugin
 	];
 	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([remark_rehype.default, { allowDangerousHtml: true }]);
 	return plugins;
@@ -12617,7 +13727,10 @@ function fileSystemContent(options) {
 			state.dirtyPaths.delete(filePath);
 			const { frontmatter, body } = parseFrontmatter(raw, options);
 			const processor = ensureProcessor(state, options);
-			const html = rewriteEmbedUrls(rewriteImageUrls(String(await processor.process(body)), slug), slug);
+			const html = rewriteEmbedUrls(rewriteImageUrls(String(await processor.process(new VFile({
+				value: body,
+				data: { slug }
+			}))), slug), slug);
 			const { readingTime, wordCount } = calculateReadingTime(body);
 			return {
 				frontmatter,
@@ -12778,6 +13891,7 @@ Object.defineProperty(exports, "Env", {
 		return types_exports$5;
 	}
 });
+exports.GalleryTrack = GalleryTrack;
 Object.defineProperty(exports, "Head", {
 	enumerable: true,
 	get: function() {