sommark 4.0.3 → 4.1.0

package/formatter/tag.js

@@ -69,6 +69,8 @@ class TagBuilder {
 		const id = this.tagName.toLowerCase();
 		const isCodeStyleOrScript = ["style", "script"].includes(id);
 		let inline_style = "";
+		const useClassFallback = options.fallbackTarget === "class";
+		const classSet = new Set();
 
 		// 1. Initial CSS Variable/Style processing
 		if (!isCodeStyleOrScript && args.style) {
@@ -83,12 +85,20 @@ class TagBuilder {
 			}
 		}
 
-		// 2. Attribute Dispatching
+		// 2. Pre-collect native classes if using class fallback
+		if (useClassFallback) {
+			if (args.class) {
+				String(args.class).split(/\s+/).filter(Boolean).forEach(c => classSet.add(c));
+			}
+		}
+
+		// 3. Attribute Dispatching
 		const keys = Object.keys(args).filter(arg => isNaN(parseInt(arg)));
 		keys.forEach(key => {
 			if (!isNaN(parseInt(key))) return; // Skip numeric positional arguments
 			if (key === "style") return;
 			if (isCodeStyleOrScript && key === "scoped") return;
+			if (useClassFallback && key === "class") return;
 
 			const isDimensionAttributeSupported = ["img", "video", "svg", "canvas", "iframe", "object", "embed"].includes(id);
 			const isWidthOrHeight = key === "width" || key === "height";
@@ -99,21 +109,35 @@ class TagBuilder {
 
 			const k = isEvent ? key.toLowerCase() : (isNative || isCustom) ? key : kebabize(key);
 
-			if (isCodeStyleOrScript) {
-				// Specialized tags: only render standard attributes, no styling fallback
-				this.#attr.push(`${k}="${escapeHTML(String(args[key]))}"`);
+			if (isCodeStyleOrScript || options.fallbackTarget === false) {
+				// Specialized tags or fallback disabled: render standard attributes, no styling fallback
+				const val = typeof args[key] === "object" ? JSON.stringify(args[key]) : args[key];
+				this.#attr.push(`${k}="${escapeHTML(String(val))}"`);
 			} else {
-				// Standard elements: process smart styling fallbacks for non-native props
+				// Standard elements: process smart fallbacks
 				if (isEvent || ((isNative || isCustom) && (!isWidthOrHeight || isDimensionAttributeSupported)) || isDataOrAria) {
 					const val = typeof args[key] === "object" ? JSON.stringify(args[key]) : args[key];
 					this.#attr.push(`${k}="${escapeHTML(String(val))}"`);
 				} else {
-					const val = typeof args[key] === "object" ? JSON.stringify(args[key]) : args[key];
-					inline_style += `${k}:${val};`;
+					if (useClassFallback) {
+						const val = args[key];
+						if (val === true || val === "true") {
+							classSet.add(k);
+						} else if (val !== false && val !== "false" && val !== null && val !== undefined) {
+							classSet.add(`${k}-${val}`);
+						}
+					} else {
+						const val = typeof args[key] === "object" ? JSON.stringify(args[key]) : args[key];
+						inline_style += `${k}:${val};`;
+					}
 				}
 			}
 		});
 
+		if (useClassFallback && classSet.size > 0) {
+			this.#attr.push(`class="${escapeHTML([...classSet].join(" "))}"`);
+		}
+
 		if (inline_style) {
 			// V4 DYNAMIC CSS: Automatically wrap CSS variables in var()
 			const processedStyle = inline_style.replace(/(^|[^\w\-_$])(--[\w\-_$]+)(?![\w\-_$]|:)/g, "$1var($2)");

package/grammar.ebnf

@@ -18,18 +18,28 @@ EscapeChar     = "\", ? any character except WhiteSpace ?;
 
 (* "Junk" refers to whitespace and comments which the parser skips in headers *)
 Comment        = "#", { ? any character except "\n" ? }, "\n";
-Junk           = { WhiteSpace | Comment };
+CommentBlock   = "###", { ? any character ? }, "###";
+Junk           = { WhiteSpace | Comment | CommentBlock };
 
 (* Prefix Layers for Dynamic Data *)
 PrefixJS       = "js{", { ? any character ? }, "}";
 PrefixP        = "p{", { ? any character ? }, "}";
-PrefixLayer    = PrefixJS | PrefixP;
+PrefixV        = "v{", { ? any character ? }, "}";
+PrefixLayer    = PrefixJS | PrefixP | PrefixV;
+
+(* Static / Runtime Logic Blocks *)
+LogicBlock     = ( "static" | "runtime" ), [ " " ], "${", { ? any character ? }, "}$";
 
 (* ========================================== *)
 (* Block Syntax (Containers)                  *)
 (* ========================================== *)
 
-Block          = BlockOpen, BlockBody, BlockEnd;
+Block          = StandardBlock | SelfClosingBlock;
+
+StandardBlock  = BlockOpen, BlockBody, BlockEnd;
+
+(* Self-Closing Blocks end with an exclamation mark (!) *)
+SelfClosingBlock = "[", Junk, BlockID, Junk, [ "=", Junk, BlockArgs, Junk ], "!", Junk, "]";
 
 (* Flexible Header with Junk-Skipping. Blocks allow colons in ID. *)
 BlockOpen      = "[", Junk, BlockID, Junk, [ "=", Junk, BlockArgs, Junk ], "]";
@@ -41,7 +51,7 @@ BlockArgs      = BlockArg, { Junk, ",", Junk, BlockArg };
 BlockArg       = [ BlockKey, Junk, ":", Junk ], Value;
 
 BlockKey       = BlockID | QuotedString;
-Value          = QuotedString | PrefixLayer | RawValue;
+Value          = QuotedString | PrefixLayer | LogicBlock | RawValue;
 
 QuotedString   = ("'" | '"'), { ? any character ? | EscapeChar }, ("'" | '"');
 RawValue       = { ? any char except ",", Junk, "]" ? | EscapeChar };
@@ -50,15 +60,16 @@ RawValue       = { ? any char except ",", Junk, "]" ? | EscapeChar };
 (* Inline Statement Syntax                    *)
 (* ========================================== *)
 
-(* Inlines use SimpleID (NO COLONS allowed in ID) *)
-InlineStatement = "(", InlineContent, ")", Junk, "->", Junk, "(", SimpleID, [ Junk, ":", Junk, InlineArgs ], ")";
+(* Inlines use SimpleID (NO COLONS allowed in ID unless key-value) *)
+InlineStatement = "(", InlineContent, ")", Junk, "->", Junk, "(", SimpleID, [ Junk, ( "=" | ":" ), Junk, InlineArgs ], ")";
 
 (* Content allows balanced parentheses and placeholders *)
-InlineContent   = { ? any char except ")" ? | BalancedParen | EscapeChar | PrefixP };
+InlineContent   = { ? any char except ")" ? | BalancedParen | EscapeChar | PrefixP | PrefixV };
 BalancedParen   = "(", InlineContent, ")";
 
-(* Inline Arguments: Positional Only *)
-InlineArgs      = Value, { Junk, ",", Junk, Value };
+(* Inline Arguments: Positional and Named support *)
+InlineArgs      = InlineArg, { Junk, ",", Junk, InlineArg };
+InlineArg       = [ SimpleID, Junk, ":", Junk ], Value;
 
 (* ========================================== *)
 (* At-Block Syntax (Raw Containers)           *)
@@ -83,4 +94,4 @@ AtBody         = { ? any character ? | EscapeChar };
 Document       = { Block | InlineStatement | AtBlock | TextContent | Comment | WhiteSpace };
 
 (* Text Content: Plain text with fallback behavior for symbols *)
-TextContent    = { ? any char except "[", "@_", "(", "#" ? | EscapeChar | PrefixP };
+TextContent    = { ? any char except "[", "@_", "(", "#" ? | EscapeChar | PrefixP | PrefixV | LogicBlock };

package/helpers/safeDataParser.js

@@ -28,7 +28,7 @@ export function safeDataParse(str) {
         if (char === '{') return parseObject();
         if (char === '[') return parseArray();
         if (char === '"' || char === "'") return parseString();
-        
+
         // Primitives or Unquoted identifiers
         return parsePrimitiveOrIdentifier();
     }
@@ -97,12 +97,12 @@ export function safeDataParse(str) {
             index++;
         }
         const token = s.slice(start, index);
-        
+
         if (token === "true") return true;
         if (token === "false") return false;
         if (token === "null") return null;
         if (!isNaN(Number(token))) return Number(token);
-        
+
         return token; // Fallback to string if it looks like an identifier
     }
 

package/helpers/spinner.js

@@ -0,0 +1,91 @@
+// Premium, dependency-free interactive terminal spinner for compilation feedback
+const spinnerFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+let spinnerIndex = 0;
+let activeSpinner = null;
+let spinnerDepth = 0;
+
+let originalStdoutWrite = null;
+let originalStderrWrite = null;
+let redrawTimeout = null;
+
+export function startSpinner() {
+	if (process.stdout.isTTY && !activeSpinner) {
+		// Hide terminal cursor for a clean premium visual feel
+		process.stdout.write("\x1b[?25l");
+
+		// Print the first frame immediately
+		const frame = spinnerFrames[spinnerIndex];
+		process.stdout.write(`\r\x1b[38;5;39m${frame}\x1b[0m \x1b[1mSomMark:\x1b[0m \x1b[38;5;208mCompiling template...\x1b[0m`);
+		spinnerIndex = (spinnerIndex + 1) % spinnerFrames.length;
+
+		// Intercept stdout and stderr writes to keep the spinner on the very bottom line
+		originalStdoutWrite = process.stdout.write;
+		process.stdout.write = function(chunk, encoding, callback) {
+			originalStdoutWrite.call(process.stdout, "\r\x1b[K");
+			const res = originalStdoutWrite.call(process.stdout, chunk, encoding, callback);
+			if (activeSpinner) {
+				if (redrawTimeout) clearTimeout(redrawTimeout);
+				redrawTimeout = setTimeout(() => {
+					if (activeSpinner && originalStdoutWrite) {
+						const f = spinnerFrames[spinnerIndex];
+						originalStdoutWrite.call(process.stdout, `\r\x1b[38;5;39m${f}\x1b[0m \x1b[1mSomMark:\x1b[0m \x1b[38;5;208mCompiling template...\x1b[0m`);
+					}
+				}, 0);
+			}
+			return res;
+		};
+
+		originalStderrWrite = process.stderr.write;
+		process.stderr.write = function(chunk, encoding, callback) {
+			if (originalStdoutWrite) {
+				originalStdoutWrite.call(process.stdout, "\r\x1b[K");
+			}
+			const res = originalStderrWrite.call(process.stderr, chunk, encoding, callback);
+			if (activeSpinner) {
+				if (redrawTimeout) clearTimeout(redrawTimeout);
+				redrawTimeout = setTimeout(() => {
+					if (activeSpinner && originalStdoutWrite) {
+						const f = spinnerFrames[spinnerIndex];
+						originalStdoutWrite.call(process.stdout, `\r\x1b[38;5;39m${f}\x1b[0m \x1b[1mSomMark:\x1b[0m \x1b[38;5;208mCompiling template...\x1b[0m`);
+					}
+				}, 0);
+			}
+			return res;
+		};
+
+		activeSpinner = setInterval(() => {
+			const frame = spinnerFrames[spinnerIndex];
+			if (originalStdoutWrite) {
+				originalStdoutWrite.call(process.stdout, `\r\x1b[38;5;39m${frame}\x1b[0m \x1b[1mSomMark:\x1b[0m \x1b[38;5;208mCompiling template...\x1b[0m`);
+			} else {
+				process.stdout.write(`\r\x1b[38;5;39m${frame}\x1b[0m \x1b[1mSomMark:\x1b[0m \x1b[38;5;208mCompiling template...\x1b[0m`);
+			}
+			spinnerIndex = (spinnerIndex + 1) % spinnerFrames.length;
+		}, 80);
+	}
+	spinnerDepth++;
+}
+
+export function stopSpinner() {
+	spinnerDepth--;
+	if (spinnerDepth <= 0) {
+		spinnerDepth = 0;
+		if (activeSpinner) {
+			clearInterval(activeSpinner);
+			activeSpinner = null;
+
+			// Restore original writes
+			if (originalStdoutWrite) {
+				process.stdout.write = originalStdoutWrite;
+				originalStdoutWrite = null;
+			}
+			if (originalStderrWrite) {
+				process.stderr.write = originalStderrWrite;
+				originalStderrWrite = null;
+			}
+
+			// Clear the spinner line and restore the terminal cursor
+			process.stdout.write("\r\x1b[K\x1b[?25h");
+		}
+	}
+}

package/helpers/utils.js

@@ -168,3 +168,49 @@ export function levenshtein(a, b) {
         }
         return matrix[b.length][a.length];
 }
+
+// -- Unresolved Placeholder Helpers ---------------------------------------- //
+
+export const UNRESOLVED_PREFIX = "SOMMARK_UNRESOLVED";
+export const UNRESOLVED_SUFFIX = "SOMMARK";
+
+/**
+ * Official method to get the unique envelope for an unresolved prefix value.
+ * @param {string} prefix - The layer ('p' or 'v').
+ * @param {string} expectedValue - The placeholder key.
+ * @returns {string} - The unique envelope string.
+ */
+export function getPrefixValue(prefix, expectedValue) {
+	if (!prefix || (prefix !== "p" && prefix !== "v")) {
+		sommarkError([
+			`<$red:getPrefixValue Error:$> {N}`,
+			`<$yellow:prefix must be 'p' or 'v'. Received:$> <$cyan:'${prefix}'$>`
+		]);
+	}
+
+	if (!expectedValue || typeof expectedValue !== "string" || expectedValue.trim() === "") {
+		sommarkError([
+			`<$red:getPrefixValue Error:$> {N}`,
+			`<$yellow:expectedValue must be a non-empty string. Received:$> <$cyan:'${expectedValue}'$>`
+		]);
+	}
+
+	return `${UNRESOLVED_PREFIX}_${prefix}_${expectedValue}_${UNRESOLVED_SUFFIX}`;
+}
+
+/**
+ * Performs a final pass on a string to clean up any remaining unresolved envelopes.
+ * @param {string} content - The content to clean.
+ * @param {string|null} [fallback] - The format to use for missing keys (e.g., "$layer{$key}" or "").
+ * @returns {string} - The cleaned content.
+ */
+export function cleanUnresolved(content, fallback = null) {
+	const pattern = new RegExp(`${UNRESOLVED_PREFIX}_(p|v)_(.+?)_${UNRESOLVED_SUFFIX}`, "g");
+	return content.replace(pattern, (match, layer, key) => {
+		if (fallback !== null) {
+			return fallback.replace("$layer", layer).replace("$key", key);
+		}
+		// Default: Keep as is or restore classic
+		return `${layer}{${key}}`;
+	});
+}

package/index.js

@@ -2,21 +2,24 @@ import lexer from "./core/lexer.js";
 import parser from "./core/parser.js";
 import transpiler from "./core/transpiler.js";
 import Mapper from "./mappers/mapper.js";
+import { registerSharedOutputs } from "./mappers/shared/index.js";
 import HTML from "./mappers/languages/html.js";
 import MARKDOWN from "./mappers/languages/markdown.js";
 import MDX from "./mappers/languages/mdx.js";
 import Json from "./mappers/languages/json.js";
+import Jsonc from "./mappers/languages/jsonc.js";
 import XML from "./mappers/languages/xml.js";
+import TEXT from "./mappers/languages/text.js";
 import { runtimeError } from "./core/errors.js";
-import FORMATS, { textFormat, htmlFormat, markdownFormat, mdxFormat, jsonFormat, xmlFormat } from "./core/formats.js";
+import FORMATS, { textFormat, htmlFormat, markdownFormat, mdxFormat, jsonFormat, jsoncFormat, xmlFormat } from "./core/formats.js";
 import TOKEN_TYPES from "./core/tokenTypes.js";
 import * as labels from "./core/labels.js";
 import { resolveModules } from "./core/modules.js";
-import { formatAST } from "./core/formatter.js";
 import { validateAST } from "./core/validator.js";
 import { enableColor } from "./helpers/colorize.js";
 import { safeArg } from "./helpers/utils.js";
-
+import { startSpinner, stopSpinner } from "./helpers/spinner.js";
+import { preprocessRuntimeLogic } from "./core/helpers/preprocessor.js";
 
 /**
  * The SomMark Core Engine.
@@ -33,28 +36,60 @@ class SomMark {
 	 * @param {Mapper|null} [options.mapperFile=null] - Custom rules for formatting.
 	 * @param {string} [options.filename="anonymous"] - The name of the file, used for errors and settings.
 	 * @param {boolean} [options.removeComments=true] - If true, comments will be removed from the final code.
-	 * @param {Object} [options.placeholders={}] - Values to use for {placeholders}.
+	 * @param {Object} [options.placeholders={}] - Values to use for p{placeholders}.
 	 * @param {Array<string>} [options.customProps=[]] - Allowed custom HTML attributes.
+	 * @param {Object} [options.importAliases={}] - Custom path aliases for modules.
 	 * @param {Array<string>} [options.importStack=[]] - Tracking for circular dependencies.
+	 * @param {string} [options.baseDir=null] - The base directory for resolving relative paths.
 	 */
-	constructor({ src, format, mapperFile = null, filename = "anonymous", removeComments = true, placeholders = {}, customProps = [], importStack = [] }) {
+	constructor(options = {}) {
+		const { src, ast = null, format, mapperFile = null, filename = "anonymous", removeComments = true, placeholders = {}, customProps = [], fallbackTarget = "style", outputValidator = null, importAliases = {}, importStack = [], baseDir = null, moduleCache = null, showSpinner = true, security = {}, generateRuntimeOutput = false, hideRuntimeOutput = false, moduleIdentityToken = null } = options;
+		this.rawSettings = options;
 		this.src = src;
+		this.ast = ast;
 		this.targetFormat = format;
 		this.mapperFile = mapperFile;
 		this.filename = filename;
 		this.removeComments = removeComments;
 		this.placeholders = placeholders;
 		this.customProps = customProps;
+		this.generateRuntimeOutput = generateRuntimeOutput;
+		this.hideRuntimeOutput = hideRuntimeOutput;
+
+		// Validate fallbackTarget
+		const VALID_FALLBACK_TARGETS = new Set(["style", "class", false]);
+		if (!VALID_FALLBACK_TARGETS.has(fallbackTarget)) {
+			runtimeError([
+				`{line}<$red:Invalid fallbackTarget$>: <$green:'${fallbackTarget}'$> <$yellow:is not a valid value.$>`,
+				`{N}<$yellow:Use$> <$green:'style'$><$yellow:,$> <$green:'class'$><$yellow:, or$> <$green:false$><$yellow:.$>{line}`
+			]);
+		}
+		this.fallbackTarget = fallbackTarget;
+		this.outputValidator = outputValidator;
+		this.importAliases = importAliases;
 		this.importStack = importStack;
+		this.baseDir = baseDir;
+		this.moduleCache = moduleCache || new Map();
+		this.showSpinner = showSpinner;
+		this.security = {
+			allowRaw: security?.allowRaw !== false,
+			maxDepth: security?.maxDepth ?? 5,
+			timeout: security?.timeout ?? 5000,
+			sanitize: typeof security?.sanitize === "function" ? security.sanitize : null,
+			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
+		};
 		this.warnings = [];
 		this._prepared = false;
 
 		// Create a random token to safely wrap data
-		this.moduleIdentityToken = `$_SM_MOD_${Math.random().toString(36).slice(2, 7)}_$`;
+		this.moduleIdentityToken = moduleIdentityToken || `$_SM_MOD_${Math.random().toString(36).slice(2, 7)}_$`;
 
 		this.Mapper = Mapper;
 
-		const mapperFiles = { [htmlFormat]: HTML, [markdownFormat]: MARKDOWN, [mdxFormat]: MDX, [jsonFormat]: Json, [xmlFormat]: XML, [textFormat]: new Mapper() };
+		const mapperFiles = { [htmlFormat]: HTML, [markdownFormat]: MARKDOWN, [mdxFormat]: MDX, [jsonFormat]: Json, [jsoncFormat]: Jsonc, [xmlFormat]: XML, [textFormat]: TEXT };
 
 		if (!this.mapperFile && this.targetFormat) {
 			const DefaultMapper = mapperFiles[this.targetFormat];
@@ -70,6 +105,9 @@ class SomMark {
 			this.mapperFile.options.moduleIdentityToken = this.moduleIdentityToken;
 			this.mapperFile.options.filename = this.filename;
 
+			this.mapperFile.options.usePrivateAttributes = this.usePrivateAttributes;
+			this.mapperFile.options.fallbackTarget = this.fallbackTarget;
+
 			// Initialize custom props whitelist
 			if (this.customProps && this.customProps.length > 0) {
 				const props = Array.isArray(this.customProps) ? this.customProps : [this.customProps];
@@ -161,6 +199,13 @@ class SomMark {
 		return tokens;
 	}
 
+	lexSync(src = this.src) {
+		this._ensurePrepared();
+		if (src !== this.src) this.src = src;
+		let tokens = lexer(this.src, this.filename);
+		return tokens;
+	}
+
 	/**
 	 * Organizes the code into a tree structure.
 	 * Also handles modules and checks for errors.
@@ -170,7 +215,7 @@ class SomMark {
 	 */
 	async parse(src = this.src) {
 		const tokens = await this.lex(src);
-		let ast = parser(tokens, this.filename, this.placeholders);
+		let ast = parser(tokens, this.filename, this.placeholders, {});
 
 		ast = await resolveModules(ast, {
 			mapperFile: this.mapperFile,
@@ -191,7 +236,7 @@ class SomMark {
 		this._ensurePrepared();
 		if (src !== this.src) this.src = src;
 		const tokens = lexer(this.src, this.filename);
-		let ast = parser(tokens, this.filename, this.placeholders);
+		let ast = parser(tokens, this.filename, this.placeholders, {});
 
 		if (this.mapperFile) {
 			validateAST(ast, this.mapperFile, this);
@@ -210,24 +255,30 @@ class SomMark {
 		if (src !== this.src) this.src = src;
 		this._ensurePrepared();
 
-		const ast = await this.parse(src);
-		let result = await transpiler({ ast, format: this.targetFormat, mapperFile: this.mapperFile });
+		if (this.showSpinner) startSpinner();
+		try {
+			const ast = this.ast || await this.parse(src);
+			let result = await transpiler({
+				ast,
+				format: this.targetFormat,
+				mapperFile: this.mapperFile,
+				security: this.security,
+				settings: this.rawSettings,
+				generateRuntimeOutput: this.generateRuntimeOutput,
+				hideRuntimeOutput: this.hideRuntimeOutput
+			});
+
+			if (this.outputValidator && typeof this.outputValidator === "function") {
+				await this.outputValidator(result);
+			}
 
-		return result;
+			return result;
+		} finally {
+			if (this.showSpinner) stopSpinner();
+		}
 	}
 
 
-	async format(options = {}) {
-		const tokens = await this.lex();
-		const ast = parser(tokens, this.filename);
-		return formatAST(ast, options);
-	}
-
-	formatSync(options = {}) {
-		const tokens = lexer(this.src, this.filename);
-		const ast = parser(tokens, this.filename);
-		return formatAST(ast, options);
-	}
 }
 
 /**
@@ -239,7 +290,13 @@ class SomMark {
  * @returns {Promise<Array<Object>>} - The list of tokens.
  */
 const lex = async (src, filename = "anonymous") => {
-	return await new SomMark({ src, filename, format: htmlFormat }).lex();
+	if (src === undefined || src === null) {
+		runtimeError([`{line}<$red:Missing Source:$> <$yellow:The 'src' argument is required for tokenization.$>{line}`]);
+	}
+	if (typeof src !== "string") {
+		runtimeError([`{line}<$red:Invalid Source Type:$> <$yellow:The 'src' argument must be a string, received ${typeof src}.$>{line}`]);
+	}
+	return lexer(src, filename);
 };
 
 /**
@@ -251,14 +308,17 @@ const lex = async (src, filename = "anonymous") => {
  * @returns {Promise<Array<Object>>} - The final code tree.
  */
 async function parse(src, filename = "anonymous") {
-	if (!src) {
+	if (src === undefined || src === null) {
 		runtimeError([`{line}<$red:Missing Source:$> <$yellow:The 'src' argument is required for parsing.$>{line}`]);
 	}
-	return await new SomMark({ src, filename, format: htmlFormat }).parse();
+	if (typeof src !== "string") {
+		runtimeError([`{line}<$red:Invalid Source Type:$> <$yellow:The 'src' argument must be a string, received ${typeof src}.$>{line}`]);
+	}
+	return await new SomMark({ src, filename, format: textFormat }).parse();
 }
 
 /**
- * The easiest way to process SomMark code.
+ * Transpiles SomMark code to a target format.
  * 
  * @param {Object} options - Transpilation options.
  * @param {string} options.src - Raw source code.
@@ -268,14 +328,16 @@ async function parse(src, filename = "anonymous") {
  * @param {boolean} [options.removeComments=true] - Strip comments.
  * @param {Object} [options.placeholders={}] - Global placeholders.
  * @param {Array<string>} [options.customProps=[]] - Custom attribute whitelist.
+ * @param {Object} [options.importAliases={}] - Custom path aliases for modules.
  * @returns {Promise<string>} - Transpiled output.
  */
 async function transpile(options = {}) {
-	const { src, format = htmlFormat, filename = "anonymous", mapperFile = null, removeComments = true, placeholders = {}, customProps = [] } = options;
 	if (typeof options !== "object" || options === null) {
 		runtimeError([`{line}<$red:Invalid Options:$> <$yellow:The options argument must be a non-null object.$>{line}`]);
 	}
-	const knownProps = ["src", "format", "filename", "mapperFile", "removeComments", "placeholders", "customProps"];
+	const { src, ast, format } = options;
+
+	const knownProps = ["src", "ast", "format", "filename", "mapperFile", "removeComments", "placeholders", "customProps", "importAliases", "fallbackTarget", "usePrivateAttributes", "outputValidator", "showSpinner", "security"];
 	Object.keys(options).forEach(key => {
 		if (!knownProps.includes(key)) {
 			runtimeError([
@@ -283,11 +345,16 @@ async function transpile(options = {}) {
 			]);
 		}
 	});
-	if (!src) {
-		runtimeError([`{line}<$red:Missing Source:$> <$yellow:The 'src' argument is required for transpilation.$>{line}`]);
+
+	if (format === undefined || format === null) {
+		runtimeError([`{line}<$red:Missing Target Format:$> <$yellow:The 'format' parameter is required for transpilation (e.g. 'html', 'markdown', 'xml', 'mdx', 'json', etc.).$>{line}`]);
+	}
+
+	if ((src === undefined || src === null) && (ast === undefined || ast === null)) {
+		runtimeError([`{line}<$red:Missing Input:$> <$yellow:Either 'src' or 'ast' must be provided for transpilation.$>{line}`]);
 	}
 
-	const sm = new SomMark({ src, format, filename, mapperFile, removeComments, placeholders, customProps });
+	const sm = new SomMark(options);
 	return await sm.transpile();
 }
 
@@ -295,9 +362,18 @@ async function transpile(options = {}) {
  * A quick, synchronous way to get tokens.
  * 
  * @param {string} src - Raw source code.
+ * @param {string} [filename="anonymous"] - Filename for error context.
  * @returns {Array<Object>} - The list of tokens.
  */
-const lexSync = src => lexer(src);
+const lexSync = (src, filename = "anonymous") => {
+	if (src === undefined || src === null) {
+		runtimeError([`{line}<$red:Missing Source:$> <$yellow:The 'src' argument is required for tokenization.$>{line}`]);
+	}
+	if (typeof src !== "string") {
+		runtimeError([`{line}<$red:Invalid Source Type:$> <$yellow:The 'src' argument must be a string, received ${typeof src}.$>{line}`]);
+	}
+	return lexer(src, filename);
+};
 
 /**
  * A quick, synchronous way to get the code tree.
@@ -306,18 +382,28 @@ const lexSync = src => lexer(src);
  * @param {Object} [options={}] - Parsing options.
  * @returns {Array<Object>} - The code tree.
  */
-const parseSync = (src, options = {}) => {
-	const { format = htmlFormat, filename = "anonymous", mapperFile = null, removeComments = true, placeholders = {}, customProps = [] } = options;
-	return new SomMark({ src, format, filename, mapperFile, removeComments, placeholders, customProps }).parseSync();
+const parseSync = (src, filename = "anonymous") => {
+	if (src === undefined || src === null) {
+		runtimeError([`{line}<$red:Missing Source:$> <$yellow:The 'src' argument is required for parsing.$>{line}`]);
+	}
+	if (typeof src !== "string") {
+		runtimeError([`{line}<$red:Invalid Source Type:$> <$yellow:The 'src' argument must be a string, received ${typeof src}.$>{line}`]);
+	}
+	const tokens = lexer(src, filename);
+	return parser(tokens, filename);
 };
 
 import { findAndLoadConfig } from "./core/helpers/config-loader.js";
 
+import Evaluator from "./core/evaluator.js";
+
 export {
+	registerSharedOutputs,
 	HTML,
 	MARKDOWN,
 	MDX,
 	Json,
+	Jsonc,
 	XML,
 	Mapper,
 	FORMATS,
@@ -326,11 +412,12 @@ export {
 	transpile,
 	lexSync,
 	parseSync,
-	formatAST,
 	TOKEN_TYPES,
 	labels,
 	enableColor,
 	safeArg,
-	findAndLoadConfig
+	findAndLoadConfig,
+	Evaluator,
+	preprocessRuntimeLogic
 };
 export default SomMark;