sommark 5.0.5 → 5.1.0

package/dist/sommark.browser.lite.js

@@ -1474,6 +1474,7 @@ function makeBlockNode() {
 		structure: "Block",
 		id: "",
 		props: {},
+		directives: {},
 		body: [],
 		depth: 0,
 		range: {
@@ -1959,9 +1960,11 @@ function parseBlock(tokens, i, filename = null, placeholders = {}, variables = {
 			i = valueIndex;
 
 			// Store Argument
-			blockNode.props[String(argIndex++)] = v;
-			if (k) {
-				blockNode.props[k] = v;
+			if (k && k.startsWith("smark-")) {
+				blockNode.directives[k.slice(6)] = v; // strip "smark-" prefix
+			} else {
+				blockNode.props[String(argIndex++)] = v;
+				if (k) blockNode.props[k] = v;
 			}
 			k = "";
 			v = "";
@@ -8798,8 +8801,27 @@ async function preprocessRuntimeLogic(code, filename = null, security = {}, inst
 				if (filename && filename !== "anonymous") {
 					baseDir = posix.dirname(posix.resolve(filename));
 				}
+
+				// Block absolute paths — path.resolve would ignore baseDir entirely
+				if (posix.isAbsolute(argValue)) {
+					transpilerError([
+						`<$red:Security Error:$> Absolute import paths are not allowed: <$magenta:${argValue}$>{line}`,
+						`<$yellow:Use a path relative to the template file, e.g.$> <$green:SomMark.import("./data.json")$> <$yellow:or$> <$green:SomMark.import("../shared/data.json")$><$yellow:.$>{line}`,
+						`<$yellow:Base directory:$> <$blue:${baseDir}$>{line}`
+					]);
+				}
+
 				const resolvedPath = posix.resolve(baseDir, argValue);
 
+				// Block path traversal — resolved path must stay inside baseDir
+				const safeBases = baseDir.endsWith(posix.sep) ? baseDir : baseDir + posix.sep;
+				if (!resolvedPath.startsWith(safeBases) && resolvedPath !== baseDir) {
+					transpilerError([
+						`<$red:Security Error:$> Import path escapes the project directory: <$magenta:${argValue}$>{line}`,
+						`<$yellow:Resolved Path:$> <$blue:${resolvedPath}$>{line}`
+					]);
+				}
+
 				const fsImpl = instance?.fs || await getNodeFs();
 
 				// File presence validation
@@ -8912,6 +8934,7 @@ const randomBytesHex = (size) => {
 
 const BODY_PLACEHOLDER = `SOMMARKBODYPLACEHOLDER${randomBytesHex(8)}SOMMARK`;
 
+
 /** 
  * Extracts all plain text from a node and its children.
  * 
@@ -9010,6 +9033,17 @@ async function generateOutput(ast, i, format, mapper_file, security = {}, parent
 
 	if (node.type === FOR_EACH) {
 		const transpiledArgs = await transpileArgs(node.props);
+
+		if (!node.props || (node.props[0] === undefined && node.props["items"] === undefined)) {
+			const line = node.range?.start?.line + 1 || 1;
+			transpilerError([
+				`<$red:Missing Prop Error in [for-each]:$>{line}`,
+				`[for-each] requires an array as its first prop, e.g. [for-each = \${ array }\$]{line}`,
+				`at line <$yellow:${line}$>{line}`
+			]);
+			return "";
+		}
+
 		const items = mapper_file ? mapper_file.safeArg({ props: transpiledArgs, index: 0, key: "items", fallBack: [] }) : [];
 
 		if (!Array.isArray(items)) {
@@ -9023,11 +9057,11 @@ async function generateOutput(ast, i, format, mapper_file, security = {}, parent
 		}
 
 		const asVar = transpiledArgs.as || "value";
-		if (asVar === "i") {
+		if (asVar === "i" || asVar === "length") {
 			const line = node.range?.start?.line + 1 || 1;
 			transpilerError([
 				`<$red:Reserved Variable Error in [for-each]:$>{line}`,
-				`'i' is a reserved variable name for the loop index.{N}Use a different name for the 'as' prop, e.g. as: "item"{line}`,
+				`'${asVar}' is a reserved variable name.{N}Use a different name for the 'as' prop, e.g. as: "item"{line}`,
 				`at line <$yellow:${line}$>{line}`
 			]);
 			return "";
@@ -9057,22 +9091,28 @@ async function generateOutput(ast, i, format, mapper_file, security = {}, parent
 			}
 		}
 
-		let output = "";
+		const rawJoin = transpiledArgs.join ?? null;
+		const join = rawJoin !== null ? rawJoin.replace(/\\n/g, "\n").replace(/\\t/g, "\t").replace(/\\r/g, "\r") : null;
+		const parts = [];
 		let idx = 0;
+		const length = items.length;
 		for (const item of items) {
 			Evaluator.pushScope();
 			Evaluator.inject({
 				[asVar]: item,
-				i: idx++
+				i: idx++,
+				length
 			});
 
+			let iterOutput = "";
 			for (let j = 0; j < cleanedBody.length; j++) {
-				output += await generateOutput(cleanedBody, j, format, mapper_file, security, parentId, generateRuntimeOutput, hideRuntimeOutput, instance, idState, extraCtx);
+				iterOutput += await generateOutput(cleanedBody, j, format, mapper_file, security, parentId, generateRuntimeOutput, hideRuntimeOutput, instance, idState, extraCtx);
 			}
 
 			await Evaluator.popScope();
+			parts.push(iterOutput);
 		}
-		return output;
+		return join !== null ? parts.join(join) : parts.join("");
 	}
 
 	let secretId = null;
@@ -9100,13 +9140,12 @@ async function generateOutput(ast, i, format, mapper_file, security = {}, parent
 	}
 
 	// smark-raw block — body collected verbatim by lexer, bypasses normal body processing pipeline
-	if (node.type === BLOCK && (node.props?.["smark-raw"] === "true" || node.props?.["smark-raw"] === true)) {
+	if (node.type === BLOCK && (node.directives?.raw === "true" || node.directives?.raw === true)) {
 		if (generateRuntimeOutput) return "";
 		const rawContent = node.body?.map(n => String(n.text || "")).join("") || "";
-		const { "smark-raw": _, ...cleanArgs } = node.props;
-		const transpiledArgs = await transpileArgs(cleanArgs);
+		const transpiledArgs = await transpileArgs(node.props);
 		if (Evaluator.active?.hasDynamicTag?.(node.id)) {
-			return await Evaluator.active.executeDynamicTag(node.id, { props: transpiledArgs, content: rawContent, textContent: rawContent });
+			return await Evaluator.active.executeDynamicTag(node.id, { props: transpiledArgs, directives: node.directives, content: rawContent, textContent: rawContent });
 		}
 		let rawTarget = mapper_file ? matchedValue(mapper_file.outputs, node.id) : null;
 		if (!rawTarget && mapper_file) rawTarget = mapper_file.getUnknownTag(node);
@@ -9114,6 +9153,7 @@ async function generateOutput(ast, i, format, mapper_file, security = {}, parent
 			const isManualMode = !!rawTarget.options?.handleAst;
 			return await rawTarget.render.call(mapper_file, {
 				props: transpiledArgs,
+				directives: node.directives,
 				content: rawContent,
 				textContent: rawContent,
 				ast: isManualMode ? node : undefined,
@@ -9225,6 +9265,7 @@ async function generateOutput(ast, i, format, mapper_file, security = {}, parent
 
 				return await target.render.call(mapper_file, {
 					props: transpiledArgs,
+					directives: node.directives,
 					content: "",
 					textContent: richText || textContent,
 					ast: cleanAst,
@@ -9243,6 +9284,7 @@ async function generateOutput(ast, i, format, mapper_file, security = {}, parent
 		}
 		result += await target.render.call(mapper_file, {
 			props: transpiledArgs,
+			directives: node.directives,
 			content,
 			textContent,
 			ast: new Proxy({}, {
@@ -10666,11 +10708,20 @@ class Mapper {
 
 /**
  * Registers universal utility blocks shared across all SomMark mappers.
- * These blocks are considered "Format Agnostic."
  *
  * @param {Mapper} mapper - The mapper instance to register tags on.
  */
 function registerSharedOutputs(mapper) {
+	mapper.register(
+		["raw", "Raw"],
+		({ content }) => {
+			return content;
+		},
+    {
+      escape: false, rules: {
+      required_directives: ["raw"]
+		} }
+	);
 }
 
 const SVG_ELEMENTS = new Set([
@@ -10823,6 +10874,7 @@ HTML.register(
 		return "";
 	},
 );
+registerSharedOutputs(HTML);
 
 /**
  * The Markdown Mapper used for generating Markdown text.
@@ -10849,42 +10901,37 @@ const MARKDOWN = Mapper.define({
 	},
 
 	/**
-	 * Provides a fallback for unknown tags by using the HTML mapper instead.
-	 */
+	 * Provides a fallback for unknown tags by rendering them as HTML elements.
+	 * Passes child nodes to the transpiler, which handles all node types (such as ForEach).
+	 **/
 	getUnknownTag(node) {
-		const id = node.id.toLowerCase();
-
+		const id = node.id;
 		return {
-			render: async ({ props, ast, isSelfClosing, renderChild }) => {
+			options: { trimAndWrapBlocks: true },
+			render: ({ props, content, isSelfClosing }) => {
 				const element = this.tag(id).smartAttributes(props, this.customProps, this.options);
 				if (isSelfClosing || VOID_ELEMENTS.has(id)) return element.selfClose();
-
-				let rawContent = "";
-				for (const child of (ast.body || [])) {
-					if (child.type === TEXT$1) rawContent += this.text(child.text);
-					else if (child.type === BLOCK) rawContent += await renderChild(child);
-				}
-				rawContent = rawContent.trim();
-
-				const meaningful = (ast.body || []).filter(c => c.type !== TEXT$1 || c.text.trim());
-				const finalContent = meaningful.length <= 1 ? rawContent : `\n${rawContent}\n`;
-				return element.body(finalContent);
-			},
-			options: { handleAst: true }
+				return element.body(content);
+			}
 		};
 	}
 });
 
 MARKDOWN.inherit(HTML);
 const { md, safeArg } = MARKDOWN;
+registerSharedOutputs(MARKDOWN);
 
 /**
  * Quote - Renders blockquote content or GFM alerts.
  */
-MARKDOWN.register("quote", ({ props, content }) => {
-	const type = safeArg({ props, index: 0, key: "type", fallBack: "" });
-	return md.quote(content, type);
-}, { resolve: true });
+MARKDOWN.register(
+	"quote",
+	({ props, content }) => {
+		const type = safeArg({ props, index: 0, key: "type", fallBack: "" });
+		return md.quote(content, type);
+	},
+	{ resolve: true }
+);
 
 /**
  * Headings - Renders H1-H6 block headings.
@@ -10964,12 +11011,12 @@ MARKDOWN.register(
 	"link",
 	({ props, content, isSelfClosing }) => {
 		if (isSelfClosing) {
-			const text  = safeArg({ props, index: 0, key: "text",  fallBack: "" });
-			const src   = safeArg({ props, index: 1, key: "src",   fallBack: "" });
+			const text = safeArg({ props, index: 0, key: "text", fallBack: "" });
+			const src = safeArg({ props, index: 1, key: "src", fallBack: "" });
 			const title = safeArg({ props, index: 2, key: "title", fallBack: "" });
 			return md.url("link", text, src, title);
 		}
-		const src   = safeArg({ props, index: 0, key: "src",   fallBack: "" });
+		const src = safeArg({ props, index: 0, key: "src", fallBack: "" });
 		const title = safeArg({ props, index: 1, key: "title", fallBack: "" });
 		return md.url("link", content, src, title);
 	},
@@ -11007,10 +11054,14 @@ MARKDOWN.register(
  * Escape - Escapes special Markdown characters.
  * Self-closing: [escape = "text" !] or [escape = text: "text" !]
  */
-MARKDOWN.register(["escape", "e"], function ({ props, content, isSelfClosing }) {
-	const text = isSelfClosing ? safeArg({ props, index: 0, key: "text", fallBack: "" }) : content;
-	return this.md.escape(text);
-}, { resolve: true });
+MARKDOWN.register(
+	["escape", "e"],
+	function ({ props, content, isSelfClosing }) {
+		const text = isSelfClosing ? safeArg({ props, index: 0, key: "text", fallBack: "" }) : content;
+		return this.md.escape(text);
+	},
+	{ resolve: true }
+);
 
 const ROW_SEP = "\x1E";
 const CELL_SEP = "\x1F";
@@ -11026,12 +11077,16 @@ MARKDOWN.register(
 		const headers = [];
 		const rows = [];
 
-		const extractRows = async (sectionNode) => {
+		const extractRows = async sectionNode => {
 			const sectionRows = [];
-			for (const child of (sectionNode.body || [])) {
+			for (const child of sectionNode.body || []) {
 				if (child.type === BLOCK && child.id?.toLowerCase() === "row") {
 					const rendered = await renderChild(child, { inTable: true });
-					const cells = rendered.split(ROW_SEP)[0]?.split(CELL_SEP).filter(c => c !== "") ?? [];
+					const cells =
+						rendered
+							.split(ROW_SEP)[0]
+							?.split(CELL_SEP)
+							.filter(c => c !== "") ?? [];
 					if (cells.length > 0) sectionRows.push(cells);
 				} else if (child.type === FOR_EACH) {
 					const rendered = await renderChild(child, { inTable: true });
@@ -11065,25 +11120,29 @@ MARKDOWN.register(
  */
 MARKDOWN.register(["header", "body"], ({ content }) => content);
 
-MARKDOWN.register("row", async function ({ ast, renderChild, inTable }) {
-	if (!inTable) {
-		let result = "";
-		for (const child of ast.body) {
-			if (child.type === TEXT$1) result += this.text(child.text);
-			else if (child.type === BLOCK) result += await renderChild(child);
+MARKDOWN.register(
+	"row",
+	async function ({ ast, renderChild, inTable }) {
+		if (!inTable) {
+			let result = "";
+			for (const child of ast.body) {
+				if (child.type === TEXT$1) result += this.text(child.text);
+				else if (child.type === BLOCK) result += await renderChild(child);
+			}
+			return result;
 		}
-		return result;
-	}
-	let cells = "";
-	for (const child of ast.body) {
-		if (child.type !== BLOCK) continue;
-		const id = child.id?.toLowerCase();
-		if (id === "cell" || id === "th" || id === "td") {
-			cells += await renderChild(child, { inTable: true });
+		let cells = "";
+		for (const child of ast.body) {
+			if (child.type !== BLOCK) continue;
+			const id = child.id?.toLowerCase();
+			if (id === "cell" || id === "th" || id === "td") {
+				cells += await renderChild(child, { inTable: true });
+			}
 		}
-	}
-	return cells + ROW_SEP;
-}, { handleAst: true });
+		return cells + ROW_SEP;
+	},
+	{ handleAst: true }
+);
 
 MARKDOWN.register(["cell", "th", "td"], ({ content, inTable }) => {
 	return inTable ? content.trim() + CELL_SEP : content;
@@ -11093,34 +11152,42 @@ MARKDOWN.register(["cell", "th", "td"], ({ content, inTable }) => {
  * Lists - Authoritative Native AST List resolution.
  * Supports Ordered (Number) and Unordered (Dotlex) lists with deep nesting.
  */
-MARKDOWN.register(["list", "List"], async function ({ ast, props, renderChild }) {
-	const indicator = safeArg({ props, index: 0, fallBack: "dot" });
-	const isOrdered = indicator === "number" || indicator === "ol";
-	const marker = isOrdered ? "" : (indicator === "dot" ? "-" : indicator);
-	const items = [];
+MARKDOWN.register(
+	["list", "List"],
+	async function ({ ast, props, renderChild }) {
+		const indicator = safeArg({ props, index: 0, fallBack: "dot" });
+		const isOrdered = indicator === "number" || indicator === "ol";
+		const marker = isOrdered ? "" : indicator === "dot" ? "-" : indicator;
+		const items = [];
 
-	for (const node of ast.body) {
-		if (node.type !== BLOCK) continue;
-		const id = node.id?.toLowerCase();
-		if (id === "item") {
-			items.push((await renderChild(node)).trim());
+		for (const node of ast.body) {
+			if (node.type !== BLOCK) continue;
+			const id = node.id?.toLowerCase();
+			if (id === "item") {
+				items.push((await renderChild(node)).trim());
+			}
 		}
-	}
 
-	return isOrdered ? md.orderedList(items, 0) : md.unorderedList(items, 0, marker);
-}, { handleAst: true, trimAndWrapBlocks: false });
+		return isOrdered ? md.orderedList(items, 0) : md.unorderedList(items, 0, marker);
+	},
+	{ handleAst: true, trimAndWrapBlocks: false }
+);
 
 /**
  * List Helpers - Internal tags for list structural organization.
  */
-MARKDOWN.register(["item", "Item"], async function ({ ast, renderChild }) {
-	let result = "";
-	for (const child of ast.body) {
-		if (child.type === TEXT$1) result += this.text(child.text);
-		else if (child.type === BLOCK) result += await renderChild(child);
-	}
-	return result.trim();
-}, { handleAst: true, trimAndWrapBlocks: false });
+MARKDOWN.register(
+	["item", "Item"],
+	async function ({ ast, renderChild }) {
+		let result = "";
+		for (const child of ast.body) {
+			if (child.type === TEXT$1) result += this.text(child.text);
+			else if (child.type === BLOCK) result += await renderChild(child);
+		}
+		return result.trim();
+	},
+	{ handleAst: true, trimAndWrapBlocks: false }
+);
 
 /**
  * Todo - Renders task list items with status markers.
@@ -11130,19 +11197,23 @@ MARKDOWN.register(["item", "Item"], async function ({ ast, renderChild }) {
  *   [todo = "Add feature", "x" !]                 positional self-closing (task, status)
  *   [todo = "x"]Add feature[end]                  status in prop, task in body
  */
-MARKDOWN.register("todo", ({ props, content, isSelfClosing }) => {
-	let status, task;
+MARKDOWN.register(
+	"todo",
+	({ props, content, isSelfClosing }) => {
+		let status, task;
 
-	if (isSelfClosing) {
-		task   = safeArg({ props, index: 0, key: "task",   fallBack: "" });
-		status = safeArg({ props, index: 1, key: "status", fallBack: "" });
-	} else {
-		status = safeArg({ props, index: 0, fallBack: "" });
-		task   = content;
-	}
+		if (isSelfClosing) {
+			task = safeArg({ props, index: 0, key: "task", fallBack: "" });
+			status = safeArg({ props, index: 1, key: "status", fallBack: "" });
+		} else {
+			status = safeArg({ props, index: 0, fallBack: "" });
+			task = content;
+		}
 
-	return md.todo(status, task);
-}, { trimAndWrapBlocks: false });
+		return md.todo(status, task);
+	},
+	{ trimAndWrapBlocks: false }
+);
 
 /**
  * The MDX Mapper used for generating Markdown with JSX.
@@ -11352,100 +11423,115 @@ Jsonc.register(["Array", "array"], async function ({ props, ast, depth = 0, inAr
 /**
  * Renders a standard XML tag based on the provided identifier and arguments.
  * Ensures strict attribute quoting and handles self-closing tags for empty bodies.
- * 
+ *
  * @param {string} id - The XML tag identifier (case-sensitive).
  * @param {Object} props - Key-value pairs to be rendered as XML attributes.
  * @param {string} content - The rendered inner content of the tag.
  * @returns {string} The fully rendered XML tag string.
  */
 const renderXmlTag = function (id, props, content, isSelfClosing) {
-    // XML is case-sensitive, so we use the exact id provided
-    const element = this.tag(id);
-
-    // Filter out positional indices (numeric keys) for XML attributes
-    const namedArgs = {};
-    Object.keys(props).forEach(key => {
-        if (isNaN(parseInt(key))) {
-            namedArgs[key] = props[key];
-        }
-    });
+	// XML is case-sensitive, so we use the exact id provided
+	const element = this.tag(id);
 
-    // In XML, attributes must always have values (strict = true)
-    element.attributes(namedArgs, true);
+	// Filter out positional indices (numeric keys) for XML attributes
+	const namedArgs = {};
+	Object.keys(props).forEach(key => {
+		if (isNaN(parseInt(key))) {
+			namedArgs[key] = props[key];
+		}
+	});
 
-    const hasBody = typeof content === "string" && content.trim().length > 0;
+	// In XML, attributes must always have values (strict = true)
+	element.attributes(namedArgs, true);
 
-    if (isSelfClosing || !hasBody) {
-        return element.selfClose();
-    }
+	const hasBody = typeof content === "string" && content.trim().length > 0;
 
-    return element.body(content);
+	if (isSelfClosing || !hasBody) {
+		return element.selfClose();
+	}
+
+	return element.body(content);
 };
 
 /**
  * The XML Mapper used for creating XML pages.
  */
 const XML = Mapper.define({
-    /**
-     * Renders a comment in XML format.
-     * @param {string} text - The comment content.
-     * @returns {string}
-     */
-    comment(text) {
-        return `<!-- ${text} -->`;
-    },
-
-    /**
-     * Resolves unknown tags by preserving their original case and applying XML rules.
-     * @param {Object} node - The AST node representing the unknown tag.
-     * @returns {Object} Renderer definition for the tag.
-     */
-    getUnknownTag(node) {
-        const id = node.id;
-        return {
-            render: ({ props, content, isSelfClosing }) => renderXmlTag.call(this, id, props, content, isSelfClosing),
-            options: {}
-        };
-    }
+	/**
+	 * Renders a comment in XML format.
+	 * @param {string} text - The comment content.
+	 * @returns {string}
+	 */
+	comment(text) {
+		return `<!-- ${text} -->`;
+	},
+
+	/**
+	 * Resolves unknown tags by preserving their original case and applying XML rules.
+	 * @param {Object} node - The AST node representing the unknown tag.
+	 * @returns {Object} Renderer definition for the tag.
+	 */
+	getUnknownTag(node) {
+		const id = node.id;
+		return {
+			render: ({ props, content, isSelfClosing }) => renderXmlTag.call(this, id, props, content, isSelfClosing),
+			options: {}
+		};
+	},
+	options: {
+		trimAndWrapBlocks: true
+	}
 });
 
 /**
  * Registers the XML declaration as a self-closing block.
  * Usage: [xml = version: "1.0", encoding: "UTF-8"]
  */
-XML.register("xml", ({ props }) => {
-    const version = props.version || "1.0";
-    const encoding = props.encoding || "UTF-8";
-    return `<?xml version="${version}" encoding="${encoding}"?>`;
-}, { rules: { is_empty_body: true } });
+XML.register(
+	"xml",
+	({ props }) => {
+		const version = props.version || "1.0";
+		const encoding = props.encoding || "UTF-8";
+		return `<?xml version="${version}" encoding="${encoding}"?>`;
+	},
+	{ rules: { is_empty_body: true } }
+);
 
 /**
  * Registers the DOCTYPE declaration.
  * Usage: [doctype = root: "note", system: "note.dtd"]
  */
-XML.register(["DOCTYPE", "doctype"], ({ props }) => {
-    const root = props.root || "root";
-    const system = props.system;
-    const pub = props.public || props.fpi;
+XML.register(
+	["DOCTYPE", "doctype"],
+	({ props }) => {
+		const root = props.root || "root";
+		const system = props.system;
+		const pub = props.public || props.fpi;
 
-    if (pub && system) {
-        return `<!DOCTYPE ${root} PUBLIC "${pub}" "${system}">`;
-    } else if (system) {
-        return `<!DOCTYPE ${root} SYSTEM "${system}">`;
-    }
-    return `<!DOCTYPE ${root}>`;
-}, { rules: { is_empty_body: true } });
+		if (pub && system) {
+			return `<!DOCTYPE ${root} PUBLIC "${pub}" "${system}">`;
+		} else if (system) {
+			return `<!DOCTYPE ${root} SYSTEM "${system}">`;
+		}
+		return `<!DOCTYPE ${root}>`;
+	},
+	{ rules: { is_empty_body: true } }
+);
 
 /**
  * Registers the XML stylesheet processing instruction.
  * Usage: [xml-stylesheet = href: "style.xsl"]
  */
-XML.register("xml-stylesheet", ({ props }) => {
-    const type = props.type || "text/xsl";
-    const href = props.href;
-    if (!href) return "";
-    return `<?xml-stylesheet type="${type}" href="${href}"?>`;
-}, { rules: { is_empty_body: true } });
+XML.register(
+	"xml-stylesheet",
+	({ props }) => {
+		const type = props.type || "text/xsl";
+		const href = props.href;
+		if (!href) return "";
+		return `<?xml-stylesheet type="${type}" href="${href}"?>`;
+	},
+	{ rules: { is_empty_body: true } }
+);
 
 /**
  * Registers CDATA sections.
@@ -11453,10 +11539,12 @@ XML.register("xml-stylesheet", ({ props }) => {
  * Self-closing: [cdata = "raw content" !] or [cdata = text: "raw content" !]
  */
 XML.register("cdata", ({ props, content, isSelfClosing }) => {
-    const text = isSelfClosing ? (props[0] ?? props.text ?? "") : content;
-    return `<![CDATA[${text}]]>`;
+	const text = isSelfClosing ? (props[0] ?? props.text ?? "") : content;
+	return `<![CDATA[${text}]]>`;
 });
 
+registerSharedOutputs(XML);
+
 const csvEscape = (value) => {
 	const str = String(value ?? "").trim();
 	if (str.includes(",") || str.includes('"') || str.includes("\n") || str.includes("\r")) {
@@ -11513,6 +11601,8 @@ CSV.register(["col", "cell", "td"], ({ textContent }) => {
 	return csvEscape(textContent);
 }, { handleAst: true, trimAndWrapBlocks: false });
 
+registerSharedOutputs(CSV);
+
 const isValidInt$1    = (v) => v !== "" && !isNaN(Number(v)) && !v.includes(".");
 const isValidFloat$1  = (v) => v !== "" && !isNaN(Number(v)) && v.includes(".");
 const isValidNumber$1 = (v) => v !== "" && !isNaN(Number(v));
@@ -11736,6 +11826,8 @@ TOML.register("array", async ({ props, ast, renderChild }) => {
 	return `${tomlKey(key)} = [${vals.join(", ")}]\n`;
 }, { handleAst: true });
 
+registerSharedOutputs(TOML);
+
 const isValidInt    = (v) => v !== "" && !isNaN(Number(v)) && !v.includes(".");
 const isValidFloat  = (v) => v !== "" && !isNaN(Number(v)) && v.includes(".");
 const isValidNumber = (v) => v !== "" && !isNaN(Number(v));
@@ -12051,6 +12143,8 @@ YAML.register("doc-start", () => "---\n", { rules: { is_empty_body: true } });
  */
 YAML.register("doc-end", () => "...\n", { rules: { is_empty_body: true } });
 
+registerSharedOutputs(YAML);
+
 /**
  * The Text Mapper used for plain-text extraction.
  */
@@ -12327,34 +12421,48 @@ async function resolveModules(ast, context) {
 	const baseDir = context.instance.baseDir || ((filename === "anonymous") ? absFilename : posix.dirname(absFilename));
 
 	// 1. Helper: Trim AST to remove file-boundary whitespace and "ghost" newlines
-	const trimAst = (nodes) => {
+	const trimAst = (nodes, trimBoundaries = true) => {
 		if (!nodes) return [];
 
-		// 1. Filter out internal whitespace-only nodes that are adjacent to non-rendering nodes
-		// (Comments, Imports, etc. shouldn't leave "ghost" newlines)
+		// 1. Filter out whitespace-only text nodes adjacent (directly or through other whitespace)
+		// to non-rendering nodes (Comments, Imports, USE_MODULE).
 		const nonRenderingTypes = [COMMENT, IMPORT, USE_MODULE];
 		let res = nodes.filter((node, idx) => {
 			if (node.type !== TEXT$1 || node.text.trim() !== "") return true;
 
-			const prev = nodes[idx - 1];
-			const next = nodes[idx + 1];
-			const isAdjacentToNonRendering =
-				(prev && nonRenderingTypes.includes(prev.type)) ||
-				(next && nonRenderingTypes.includes(next.type));
+			// Walk backwards through consecutive whitespace nodes to find prev non-whitespace
+			let prevIsNonRendering = false;
+			for (let j = idx - 1; j >= 0; j--) {
+				if (nodes[j].type === TEXT$1 && nodes[j].text.trim() === "") continue;
+				prevIsNonRendering = nonRenderingTypes.includes(nodes[j].type);
+				break;
+			}
+
+			// Walk forwards through consecutive whitespace nodes to find next non-whitespace
+			let nextIsNonRendering = false;
+			for (let j = idx + 1; j < nodes.length; j++) {
+				if (nodes[j].type === TEXT$1 && nodes[j].text.trim() === "") continue;
+				nextIsNonRendering = nonRenderingTypes.includes(nodes[j].type);
+				break;
+			}
 
-			return !isAdjacentToNonRendering;
+			return !(prevIsNonRendering || nextIsNonRendering);
 		});
 
-		// 2. Final pass: trim leading/trailing newlines from the remaining boundary text nodes
-		if (res.length > 0 && res[0].type === TEXT$1) {
-			res[0].text = res[0].text.replace(/^[\r\n]+/, "");
-		}
-		if (res.length > 0 && res[res.length - 1].type === TEXT$1) {
-			res[res.length - 1].text = res[res.length - 1].text.replace(/[\r\n]+\s*$/, "");
+		if (trimBoundaries) {
+			// 2. Final pass: trim leading/trailing newlines from the remaining boundary text nodes
+			if (res.length > 0 && res[0].type === TEXT$1) {
+				res[0].text = res[0].text.replace(/^[\r\n]+/, "");
+			}
+			if (res.length > 0 && res[res.length - 1].type === TEXT$1) {
+				res[res.length - 1].text = res[res.length - 1].text.replace(/[\r\n]+\s*$/, "");
+			}
+
+			// 3. Remove any nodes that became purely empty after trimming
+			res = res.filter(node => node.type !== TEXT$1 || node.text !== "");
 		}
 
-		// 3. Remove any nodes that became purely empty after trimming
-		return res.filter(node => node.type !== TEXT$1 || node.text !== "");
+		return res;
 	};
 
 	// 2. Helper: Inject Slots with Indentation Propagation
@@ -12425,6 +12533,10 @@ async function resolveModules(ast, context) {
 				// 1b. Resolve relative to current base (FS)
 				const absolutePath = resolveModulePath(resolvedPath, currentBaseDir);
 
+				if (!context.instance.fs) {
+					runtimeError([`<$red:Module Error:$> Cannot import <$magenta:${filePath}$> — no filesystem is available.{N}In browser mode, pass a URL-based <$cyan:baseDir$> or a <$cyan:files$> map to enable module loading.`]);
+				}
+
 				// Local Path Resolution with Auto-Extension
 				let localPath = absolutePath;
 				if (!await context.instance.fs.exists(localPath) && !localPath.endsWith(".smark")) {
@@ -12576,7 +12688,6 @@ async function resolveModules(ast, context) {
 						Object.entries(node.props).filter(([key]) => {
 							if (key === "__consumed__") return false;
 							if (consumed.has(key)) return false; // THE FIX: Filter if hit by v{}
-							if (key === "smark-raw") return false; // directive — must not leak onto root element
 							return true;
 						})
 					);
@@ -12691,10 +12802,7 @@ const runValidations = (node, target, instance) => {
 	const isStructural = node.type === "Block";
 	if (isStructural && rules.required_args && Array.isArray(rules.required_args)) {
 		const missingArgs = rules.required_args.filter(arg => {
-			// Check if the argument exists in named args or as a positional arg (if arg is a number)
-			if (typeof arg === "number") {
-				return node.props[arg] === undefined;
-			}
+			if (typeof arg === "number") return node.props[arg] === undefined;
 			return node.props[arg] === undefined;
 		});
 
@@ -12709,6 +12817,22 @@ const runValidations = (node, target, instance) => {
 			);
 		}
 	}
+
+	// -- Directives Validation (Required Directives) ----------------------- //
+	if (isStructural && rules.required_directives && Array.isArray(rules.required_directives)) {
+		const missingDirectives = rules.required_directives.filter(key => node.directives?.[key] === undefined);
+
+		if (missingDirectives.length > 0) {
+			transpilerError(
+				[
+					"{N}",
+					`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:is missing required directive props:$> <$red:${missingDirectives.map(k => `smark-${k}`).join(", ")}$>{N}`,
+					`<$blue:Please ensure these directive props are provided in the template usage.$>`
+				],
+				context
+			);
+		}
+	}
 };
 
 /**
@@ -12880,6 +13004,14 @@ function setDefaultFs(fs) {
 	Evaluator.setDefaultFs(fs);
 }
 
+function setDefaultEnv(env) {
+	Evaluator.setDefaultEnv(env);
+}
+
+function setDefaultAsyncLocalStorage(cls) {
+	Evaluator.setDefaultAsyncLocalStorage(cls);
+}
+
 function setDefaultResolvePath(fn) {
 	defaultResolvePath = fn;
 }
@@ -12951,7 +13083,8 @@ class SomMark {
 			allowFetch: security?.allowFetch !== false,
 			allowHttp: security?.allowHttp === true,
 			allowedOrigins: Array.isArray(security?.allowedOrigins) ? security.allowedOrigins.map(o => o.toLowerCase()) : null,
-			allowedExtensions: Array.isArray(security?.allowedExtensions) ? security.allowedExtensions.map(e => e.toLowerCase()) : null
+			allowedExtensions: Array.isArray(security?.allowedExtensions) ? security.allowedExtensions.map(e => e.toLowerCase()) : null,
+			env: Array.isArray(security?.env) ? security.env : []
 		};
 		this.warnings = [];
 		this._prepared = false;
@@ -13262,8 +13395,24 @@ async function findAndLoadConfig(targetPath) {
 	return await defaultFindAndLoadConfig(targetPath);
 }
 
+class AsyncLocalStorage {
+  #store = undefined;
+  run(store, fn) {
+    const prev = this.#store;
+    this.#store = store;
+    try { return fn(); }
+    finally { this.#store = prev; }
+  }
+  getStore() { return this.#store; }
+  exit(fn) { return fn(); }
+  enterWith(store) { this.#store = store; }
+  disable() {}
+}
+
 setDefaultFs(null);
 setDefaultCwd("/");
+setDefaultEnv(null);
+setDefaultAsyncLocalStorage(AsyncLocalStorage);
 
 /**
  * Resolves a relative path into a full URL using the current document location.
@@ -13345,4 +13494,4 @@ function renderCompiledHTML(container, html) {
     }
 }
 
-export { CSV, Evaluator, formats as FORMATS, HTML, Json, Jsonc, MARKDOWN, MDX, Mapper, TOKEN_TYPES, TOML, XML, YAML, SomMark as default, enableColor, findAndLoadConfig, labels, lex, lexSync, parse, parseSync, preprocessRuntimeLogic, registerSharedOutputs, renderCompiledHTML, resolveBaseDir, safeArg$1 as safeArg, setDefaultCwd, setDefaultFindAndLoadConfig, setDefaultFs, setDefaultResolvePath, transpile };
+export { CSV, Evaluator, formats as FORMATS, HTML, Json, Jsonc, MARKDOWN, MDX, Mapper, TOKEN_TYPES, TOML, XML, YAML, SomMark as default, enableColor, findAndLoadConfig, labels, lex, lexSync, parse, parseSync, preprocessRuntimeLogic, registerSharedOutputs, renderCompiledHTML, resolveBaseDir, safeArg$1 as safeArg, setDefaultAsyncLocalStorage, setDefaultCwd, setDefaultEnv, setDefaultFindAndLoadConfig, setDefaultFs, setDefaultResolvePath, transpile };