sommark 3.3.0 → 3.3.2

package/SOMMARK-SPEC.md

@@ -50,8 +50,6 @@ Identifiers **must not contain spaces**.
 
 # 2. Blocks
 
-> At the top level, only Blocks and comments are permitted.
-
 
 Blocks are hierarchical containers that can contain other blocks, inline statements, or plain text.
 

package/cli/commands/build.js

@@ -39,7 +39,7 @@ export async function runBuild(format_option, sourcePath, outputFlag, outputFile
         if (await isExist(sourcePath)) {
             const file = path.parse(sourcePath);
             if (file.ext === ".smark") {
-                const config = await loadConfig();
+                const config = await loadConfig(sourcePath);
 
                 const success_msg = (outputDir, outputFile, size, date) => {
                     return formatMessage(

package/cli/commands/init.js

@@ -20,6 +20,9 @@ export function getConfigDir() {
 
 export async function runInit() {
     try {
+        const configDir = getConfigDir();
+        const configFilePath = path.join(configDir, "smark.config.js");
+
         // ======================================================
         // Create configuration directory
         // ======================================================

package/cli/commands/print.js

@@ -33,7 +33,7 @@ export async function printLex(filePath) {
     const fileName = path.basename(filePath);
     console.log(formatMessage(`{line}<$blue: Printing tokens for$> <$yellow:'${fileName}'$>{line}`));
     const source_code = await readContent(filePath);
-    const config = await loadConfig();
+    const config = await loadConfig(filePath);
 
     const absolutePath = path.resolve(process.cwd(), filePath);
     const smark = new SomMark({
@@ -59,7 +59,7 @@ export async function printParse(filePath) {
     const fileName = path.basename(filePath);
     console.log(formatMessage(`{line}<$blue: Printing AST for$> <$yellow:'${fileName}'$>{line}`));
     const source_code = await readContent(filePath);
-    const config = await loadConfig();
+    const config = await loadConfig(filePath);
 
     const absolutePath = path.resolve(process.cwd(), filePath);
     const smark = new SomMark({

package/cli/helpers/config.js

@@ -1,62 +1,17 @@
-import path from "node:path";
-import { pathToFileURL } from "node:url";
-import { isExist } from "./file.js";
-import { getConfigDir } from "../commands/init.js";
+import { findAndLoadConfig } from "../../core/helpers/config-loader.js";
 
 // ========================================================================== //
 //  Configuration Loader                                                      //
 // ========================================================================== //
 
-const CONFIG_FILE_NAME = "smark.config.js";
-const currentDir = process.cwd();
-const localConfigPath = path.join(currentDir, CONFIG_FILE_NAME);
-
-// ========================================================================== //
-//  Default Configuration                                                     //
-// ========================================================================== //
-let config = {
-    outputFile: "output",
-    outputDir: "",
-    mappingFile: "",
-    plugins: [],
-    priority: []
-};
-
-// ========================================================================== //
-//  Load Configuration                                                        //
-// ========================================================================== //
 let resolvedConfigPath = null;
 
-export async function loadConfig() {
-    const userConfigPath = path.join(getConfigDir(), CONFIG_FILE_NAME);
-    let targetConfigPath = null;
-
-    if (await isExist(localConfigPath)) {
-        targetConfigPath = localConfigPath;
-    } else if (await isExist(userConfigPath)) {
-        targetConfigPath = userConfigPath;
-    }
-
-    resolvedConfigPath = targetConfigPath;
-
-    if (targetConfigPath) {
-        try {
-            const configURL = pathToFileURL(targetConfigPath).href;
-            const loadedModule = await import(configURL);
-            config = loadedModule.default || loadedModule;
-        } catch (error) {
-            console.error(`Error loading configuration file ${targetConfigPath}:`, error.message);
-        }
-    } else {
-        // console.log(`${CONFIG_FILE_NAME} not found. Using default configuration.`);
-    }
-
-    if (!config.outputDir) {
-        config.outputDir = process.cwd();
-    }
-    return config;
+export async function loadConfig(filename = null) {
+	const config = await findAndLoadConfig(filename);
+	resolvedConfigPath = config.resolvedConfigPath;
+	return config;
 }
 
 export function getResolvedConfigPath() {
-    return resolvedConfigPath;
+	return resolvedConfigPath;
 }

package/cli/helpers/transpile.js

@@ -16,7 +16,7 @@ const default_mapperFiles = { [htmlFormat]: HTML, [markdownFormat]: MARKDOWN, [m
 //  Transpile Function                                                        //
 // ========================================================================== //
 export async function transpile({ src, format, filename = null, mappingFile = "" }) {
-    const config = await loadConfig();
+    const config = await loadConfig(filename);
     let finalMapper = mappingFile;
 
     // 1. Resolve Mapping File

package/core/errors.js

@@ -38,6 +38,34 @@ function formatMessage(text) {
 	return text;
 }
 
+/**
+ * Formats an error with source context (line number, code snippet, pointer).
+ */
+function formatErrorWithContext(src, range, filename, message, typeName) {
+	if (!src || !range || !range.start) return message;
+
+	const lines = src.split("\n");
+	const lineIndex = range.start.line;
+	const lineContent = lines[lineIndex] || "";
+	const pointerPadding = " ".repeat(range.start.character);
+	const sourceLabel = filename ? ` [${filename}]` : "";
+
+	const rangeInfo =
+		range.start.line === range.end.line
+			? `from column <$yellow:${range.start.character}$> to <$yellow:${range.end.character}$>`
+			: `from line <$yellow:${range.start.line + 1}$>, column <$yellow:${range.start.character}$> to line <$yellow:${range.end.line + 1}$>, column <$yellow:${range.end.character}$>`;
+
+	const formattedMessage = [
+		`<$blue:{line}$><$red:Here where error occurred${sourceLabel}:$>{N}${lineContent}{N}${pointerPadding}<$yellow:^$>{N}{N}`,
+		`<$red:${typeName} Error:$> `,
+		...(Array.isArray(message) ? message : [message]),
+		`{N}at line <$yellow:${range.start.line + 1}$>, ${rangeInfo}{N}`,
+		"<$blue:{line}$>"
+	];
+
+	return formattedMessage;
+}
+
 // ========================================================================== //
 //  Error Classes                                                            //
 // ========================================================================== //
@@ -94,45 +122,39 @@ class SommarkError extends CustomError {
 // ========================================================================== //
 
 function getError(type) {
-	const validate_msg = msg => Array.isArray(msg) && msg.length > 0;
-	switch (type) {
-		case "parser":
-			return errorMessage => {
-				if (validate_msg(errorMessage)) {
-					throw new ParserError(errorMessage).message;
-				}
-			};
-		case "transpiler":
-			return errorMessage => {
-				if (validate_msg(errorMessage)) {
-					throw new TranspilerError(errorMessage).message;
-				}
-			};
-		case "lexer":
-			return errorMessage => {
-				if (validate_msg(errorMessage)) {
-					throw new LexerError(errorMessage).message;
-				}
-			};
-		case "cli":
-			return errorMessage => {
-				if (validate_msg(errorMessage)) {
-					throw new CLIError(errorMessage).message;
-				}
-			};
-		case "runtime":
-			return errorMessage => {
-				if (validate_msg(errorMessage)) {
-					throw new RuntimeError(errorMessage).message;
-				}
-			};
-		case "sommark":
-			return errorMessage => {
-				if (validate_msg(errorMessage)) {
-					throw new SommarkError(errorMessage).message;
-				}
-			};
-	}
+	const validate_msg = msg => (Array.isArray(msg) && msg.length > 0) || typeof msg === "string";
+	const typeNames = {
+		parser: "Parser",
+		transpiler: "Transpiler",
+		lexer: "Lexer",
+		cli: "CLI",
+		runtime: "Runtime",
+		sommark: "SomMark"
+	};
+	const ErrorClasses = {
+		parser: ParserError,
+		transpiler: TranspilerError,
+		lexer: LexerError,
+		cli: CLIError,
+		runtime: RuntimeError,
+		sommark: SommarkError
+	};
+
+	return (errorMessage, context = null) => {
+		if (validate_msg(errorMessage)) {
+			let finalMessage = errorMessage;
+			if (context && context.src && context.range) {
+				finalMessage = formatErrorWithContext(
+					context.src,
+					context.range,
+					context.filename,
+					errorMessage,
+					typeNames[type]
+				);
+			}
+			throw new ErrorClasses[type](finalMessage).message;
+		}
+	};
 }
 
 const lexerError = getError("lexer");

package/core/helpers/config-loader.js

@@ -0,0 +1,101 @@
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs/promises";
+import { pathToFileURL, fileURLToPath } from "node:url";
+
+const CONFIG_FILE_NAME = "smark.config.js";
+
+/**
+ * Gets the global configuration directory based on the OS.
+ */
+export function getConfigDir() {
+	const homeDir = os.homedir();
+	if (process.platform === "win32") {
+		return path.join(process.env.APPDATA || path.join(homeDir, "AppData", "Roaming"), "sommark");
+	} else if (process.platform === "darwin") {
+		return path.join(homeDir, "Library", "Application Support", "sommark");
+	} else {
+		return path.join(process.env.XDG_CONFIG_HOME || path.join(homeDir, ".config"), "sommark");
+	}
+}
+
+/**
+ * Recursively searches for smark.config.js up the directory tree starting from startDir.
+ */
+async function findConfig(startDir) {
+	let currentDir = startDir;
+	while (currentDir !== path.parse(currentDir).root) {
+		const configPath = path.join(currentDir, CONFIG_FILE_NAME);
+		try {
+			await fs.access(configPath);
+			return configPath;
+		} catch {
+			currentDir = path.dirname(currentDir);
+		}
+	}
+	return null;
+}
+
+/**
+ * Loads the configuration from a file.
+ */
+async function loadConfigFile(configPath) {
+	if (!configPath) return null;
+	try {
+		// Use a timestamp to bypass cache for dynamic updates in LSP
+		const configURL = `${pathToFileURL(configPath).href}?t=${Date.now()}`;
+		const loadedModule = await import(configURL);
+		return loadedModule.default || loadedModule;
+	} catch (error) {
+		return null;
+	}
+}
+
+/**
+ * Finds and loads the configuration starting from targetPath.
+ * Checks local directory, parent directories, and finally the global config directory.
+ */
+export async function findAndLoadConfig(targetPath) {
+	const startDir = targetPath ? (await fs.stat(targetPath)).isDirectory() ? targetPath : path.dirname(targetPath) : process.cwd();
+	
+	let configPath = await findConfig(startDir);
+	
+	if (!configPath) {
+		// As a fallback, check the current working directory of the process
+		// This helps LSP find the project config when running in the project root
+		const localConfigPath = path.join(process.cwd(), CONFIG_FILE_NAME);
+		try {
+			await fs.access(localConfigPath);
+			configPath = localConfigPath;
+		} catch {
+			// Not in CWD
+		}
+	}
+
+	if (!configPath) {
+		const globalConfigPath = path.join(getConfigDir(), CONFIG_FILE_NAME);
+		try {
+			await fs.access(globalConfigPath);
+			configPath = globalConfigPath;
+		} catch {
+			// No config found
+		}
+	}
+
+	const defaultConfig = {
+		outputFile: "output",
+		outputDir: startDir,
+		mappingFile: null,
+		plugins: [],
+		priority: []
+	};
+
+	if (configPath) {
+		const loadedConfig = await loadConfigFile(configPath);
+		if (loadedConfig) {
+			return { ...defaultConfig, ...loadedConfig, resolvedConfigPath: configPath };
+		}
+	}
+
+	return { ...defaultConfig, resolvedConfigPath: null };
+}

package/core/plugins/rules-validation-plugin.js

@@ -10,7 +10,7 @@ const RulesValidationPlugin = {
 	type: "on-ast",
 	author: "Adam-Elmi",
 	description: "Checks your document to make sure all tags and arguments follow the rules set in the mapper.",
-	onAst(ast, { mapperFile }) {
+	onAst(ast, { mapperFile, instance }) {
 		if (!mapperFile) return ast;
 
 		const validateNode = (node, parentTarget = null) => {
@@ -20,7 +20,7 @@ const RulesValidationPlugin = {
 			//  1. TEXT nodes validation                                                  //
 			// ========================================================================== //
 			if (node.type === "Text" && parentTarget) {
-				this.runValidations(parentTarget, null, node.text, "Text", mapperFile);
+				this.runValidations(node, parentTarget, null, node.text, "Text", mapperFile, instance);
 			}
 
 			// ========================================================================== //
@@ -29,7 +29,7 @@ const RulesValidationPlugin = {
 			if (node.id) {
 				const target = mapperFile.get(node.id);
 				if (target) {
-					this.runValidations(target, node.args, this.getContent(node), node.type, mapperFile);
+					this.runValidations(node, target, node.args, this.getContent(node), node.type, mapperFile, instance);
 				}
 			}
 
@@ -54,10 +54,11 @@ const RulesValidationPlugin = {
 		return "";
 	},
 
-	runValidations(target, args, content, type, mapperFile) {
+	runValidations(node, target, args, content, type, mapperFile, instance) {
 		if (!target.options) return;
 		const rules = target.options.rules || {};
 		const id = Array.isArray(target.id) ? target.id.join(" | ") : target.id;
+		const context = instance ? { src: instance.src, range: node.range, filename: instance.filename } : null;
 
 		// ========================================================================== //
 		//  1. Validate Args Count & Keys                                             //
@@ -68,24 +69,33 @@ const RulesValidationPlugin = {
 			const argCount = args.length;
 
 			if (min !== undefined && argCount < min) {
-				transpilerError([
-					"{line}<$red:Validation Error:$> ",
-					`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:requires at least$> <$green:${min}$> <$yellow:argument(s). Found$> <$red:${argCount}$>{line}`
-				]);
+				transpilerError(
+					[
+						"<$red:Validation Error:$> ",
+						`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:requires at least$> <$green:${min}$> <$yellow:argument(s). Found$> <$red:${argCount}$>`
+					],
+					context
+				);
 			}
 			if (max !== undefined && argCount > max) {
-				transpilerError([
-					"{line}<$red:Validation Error:$> ",
-					`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:accepts at most$> <$green:${max}$> <$yellow:argument(s). Found$> <$red:${argCount}$>{line}`
-				]);
+				transpilerError(
+					[
+						"<$red:Validation Error:$> ",
+						`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:accepts at most$> <$green:${max}$> <$yellow:argument(s). Found$> <$red:${argCount}$>`
+					],
+					context
+				);
 			}
 			if (required && Array.isArray(required)) {
 				const missingKeys = required.filter(key => !Object.prototype.hasOwnProperty.call(args, key));
 				if (missingKeys.length > 0) {
-					transpilerError([
-						"{line}<$red:Validation Error:$> ",
-						`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:is missing required argument(s):$> <$red:${missingKeys.join(", ")}$>{line}`
-					]);
+					transpilerError(
+						[
+							"<$red:Validation Error:$> ",
+							`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:is missing required argument(s):$> <$red:${missingKeys.join(", ")}$>`
+						],
+						context
+					);
 				}
 			}
 			if (includes && Array.isArray(includes)) {
@@ -93,11 +103,14 @@ const RulesValidationPlugin = {
 					return !includes.includes(key) && !mapperFile.extraProps.has(key);
 				});
 				if (invalidKeys.length > 0) {
-					transpilerError([
-						"{line}<$red:Validation Error:$> ",
-						`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:contains invalid argument key(s):$> <$red:${invalidKeys.join(", ")}$>`,
-						`{N}<$yellow:Allowed keys are:$> <$green:${includes.join(", ")}$>{line}`
-					]);
+					transpilerError(
+						[
+							"<$red:Validation Error:$> ",
+							`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:contains invalid argument key(s):$> <$red:${invalidKeys.join(", ")}$>`,
+							`{N}<$yellow:Allowed keys are:$> <$green:${includes.join(", ")}$>`
+						],
+						context
+					);
 				}
 			}
 		}
@@ -114,10 +127,13 @@ const RulesValidationPlugin = {
 				if (keyPattern) {
 					const invalidKeys = argKeys.filter(key => !keyPattern.test(key));
 					if (invalidKeys.length > 0) {
-						transpilerError([
-							"{line}<$red:Validation Error:$> ",
-							`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:contains argument keys that do not match pattern $> <$green:${keyPattern.toString()}$>: <$red:${invalidKeys.join(", ")}$>{line}`
-						]);
+						transpilerError(
+							[
+								"<$red:Validation Error:$> ",
+								`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:contains argument keys that do not match pattern $> <$green:${keyPattern.toString()}$>: <$red:${invalidKeys.join(", ")}$>`
+							],
+							context
+						);
 					}
 				}
 			}
@@ -131,15 +147,21 @@ const RulesValidationPlugin = {
 						const valueRule = rules.values[key];
 						if (valueRule) {
 							if (valueRule instanceof RegExp && !valueRule.test(value)) {
-								transpilerError([
-									"{line}<$red:Validation Error:$> ",
-									`<$yellow:Argument key$> <$blue:'${key}'$> <$yellow:in$> <$blue:'${id}'$> <$yellow:has invalid value:$> <$red:'${value}'$>{N}<$yellow:Expected to match pattern:$> <$green:${valueRule.toString()}$>{line}`
-								]);
+								transpilerError(
+									[
+										"<$red:Validation Error:$> ",
+										`<$yellow:Argument key$> <$blue:'${key}'$> <$yellow:in$> <$blue:'${id}'$> <$yellow:has invalid value:$> <$red:'${value}'$>{N}<$yellow:Expected to match pattern:$> <$green:${valueRule.toString()}$>`
+									],
+									context
+								);
 							} else if (typeof valueRule === "function" && !valueRule(value)) {
-								transpilerError([
-									"{line}<$red:Validation Error:$> ",
-									`<$yellow:Argument key$> <$blue:'${key}'$> <$yellow:in$> <$blue:'${id}'$> <$yellow:failed custom validation for value:$> <$red:'${value}'$>{line}`
-								]);
+								transpilerError(
+									[
+										"<$red:Validation Error:$> ",
+										`<$yellow:Argument key$> <$blue:'${key}'$> <$yellow:in$> <$blue:'${id}'$> <$yellow:failed custom validation for value:$> <$red:'${value}'$>`
+									],
+									context
+								);
 							}
 						}
 					}
@@ -153,16 +175,22 @@ const RulesValidationPlugin = {
 		if (content !== undefined && rules.content) {
 			const { maxLength, match } = rules.content;
 			if (maxLength && content.length > maxLength) {
-				transpilerError([
-					"{line}<$red:Validation Error:$> ",
-					`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:content exceeds maximum length of$> <$green:${maxLength}$> <$yellow:characters. Found$> <$red:${content.length}$>{line}`
-				]);
+				transpilerError(
+					[
+						"<$red:Validation Error:$> ",
+						`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:content exceeds maximum length of$> <$green:${maxLength}$> <$yellow:characters. Found$> <$red:${content.length}$>`
+					],
+					context
+				);
 			}
 			if (match && match instanceof RegExp && !match.test(content)) {
-				transpilerError([
-					"{line}<$red:Validation Error:$> ",
-					`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:content does not match required pattern:$> <$green:${match.toString()}$>{line}`
-				]);
+				transpilerError(
+					[
+						"<$red:Validation Error:$> ",
+						`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:content does not match required pattern:$> <$green:${match.toString()}$>`
+					],
+					context
+				);
 			}
 		}
 
@@ -171,10 +199,13 @@ const RulesValidationPlugin = {
 		// ========================================================================== //
 		if (rules.is_self_closing && (type === "Block" || content)) {
 			if (content) {
-				transpilerError([
-					"{line}<$red:Validation Error:$> ",
-					`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:is self-closing tag and is not allowed to have a content | children$>{line}`
-				]);
+				transpilerError(
+					[
+						"<$red:Validation Error:$> ",
+						`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:is self-closing tag and is not allowed to have a content | children$>`
+					],
+					context
+				);
 			}
 		}
 
@@ -185,10 +216,13 @@ const RulesValidationPlugin = {
 		if (typeToValidate && type !== "Text") {
 			const allowedTypes = Array.isArray(typeToValidate) ? typeToValidate : [typeToValidate];
 			if (!allowedTypes.includes("any") && !allowedTypes.includes(type)) {
-				transpilerError([
-					"{line}<$red:Validation Error:$> ",
-					`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:is expected to be type$> <$green:'${allowedTypes.join(" | ")}'$>{N}<$cyan:Received type: $> <$magenta:'${type}'$>{line}`
-				]);
+				transpilerError(
+					[
+						"<$red:Validation Error:$> ",
+						`<$yellow:Identifier$> <$blue:'${id}'$> <$yellow:is expected to be type$> <$green:'${allowedTypes.join(" | ")}'$>{N}<$cyan:Received type: $> <$magenta:'${type}'$>`
+					],
+					context
+				);
 			}
 		}
 	}

package/core/plugins/sommark-format.js

@@ -54,6 +54,11 @@ export default {
 		// ========================================================================== //
 		//  2. Formatting Logic                                                      //
 		// ========================================================================== //
+		const shouldQuote = (val) => {
+			if (typeof val !== "string") return false;
+			return /[ \t\n\r,:[\]()@#]/.test(val);
+		};
+
 		const formatArgs = (args, type) => {
 			if (!args || args.length === 0) return "";
 			let usedKeys = new Set();
@@ -73,8 +78,15 @@ export default {
 				}
 
 				let escapedVal = escapeArg(val, type);
+				if (shouldQuote(val)) {
+					const quotedVal = String(val)
+						.replace(/\\/g, "\\\\")
+						.replace(/"/g, '\\"');
+					escapedVal = `"${quotedVal}"`;
+				}
+
 				if (matchedKey) {
-					formattedArgs.push(`${matchedKey}:${escapedVal}`);
+					formattedArgs.push(`${matchedKey}: ${escapedVal}`);
 				} else {
 					formattedArgs.push(escapedVal);
 				}
@@ -183,7 +195,8 @@ export default {
 							result += `${innerIndentStr}[end]\n`;
 						} else if (child.type === "AtBlock") {
 							const argsStr = formatArgs(child.args, "AtBlock");
-							result += `${innerIndentStr}@_${child.id}_@${argsStr}\n`;
+							const atHeader = argsStr ? `@_${child.id}_@${argsStr}` : `@_${child.id}_@;`;
+							result += `${innerIndentStr}${atHeader}\n`;
 							if (child.content) {
 								// ========================================================================== //
 								//  Remove leading spaces from messy text block and re-indent         //

package/index.js

@@ -32,6 +32,7 @@ class SomMark {
 		this.priority = priority;
 		this.filename = filename;
 		this.warnings = [];
+		this._prepared = false;
 
 		// 1. Identify which built-in plugins should be active by default
 		const inactiveByDefault = ["raw-content", "sommark-format"];
@@ -188,29 +189,10 @@ class SomMark {
 
 		return processed;
 	}
+	
+	_ensurePrepared() {
+		if (this._prepared) return;
 
-	async lex(src = this.src) {
-		if (src !== this.src) this.src = src;
-		const processedSrc = await this._applyScopedPreprocessors(this.src);
-		let tokens = lexer(processedSrc, this.filename);
-		tokens = await this.pluginManager.runAfterLex(tokens);
-		return tokens;
-	}
-
-	async parse(src = this.src) {
-		const tokens = await this.lex(src);
-		let ast = parser(tokens, this.filename);
-		ast = await this.pluginManager.runOnAst(ast, { 
-			mapperFile: this.mapperFile, 
-			filename: this.filename,
-			format: this.format,
-			instance: this
-		});
-		return ast;
-	}
-
-	async transpile(src = this.src) {
-		if (src !== this.src) this.src = src;
 		// 1. Resolve Dynamic Formats from Plugins if built-in failed
 		if (!this.mapperFile) {
 			const PluginMapper = this.pluginManager.getFormatMapper(this.format);
@@ -230,8 +212,6 @@ class SomMark {
 		// Run active registration hooks from plugins
 		this.pluginManager.runRegisterHooks(this);
 
-		const ast = await this.parse(src);
-
 		// 2. Extend Mapper with static plugins definitions
 		const extensions = this.pluginManager.getMapperExtensions();
 		if (extensions.outputs.length > 0) {
@@ -256,6 +236,36 @@ class SomMark {
 			}
 		}
 
+		this._prepared = true;
+	}
+
+	async lex(src = this.src) {
+		this._ensurePrepared();
+		if (src !== this.src) this.src = src;
+		const processedSrc = await this._applyScopedPreprocessors(this.src);
+		let tokens = lexer(processedSrc, this.filename);
+		tokens = await this.pluginManager.runAfterLex(tokens);
+		return tokens;
+	}
+
+	async parse(src = this.src) {
+		const tokens = await this.lex(src);
+		let ast = parser(tokens, this.filename);
+		ast = await this.pluginManager.runOnAst(ast, { 
+			mapperFile: this.mapperFile, 
+			filename: this.filename,
+			format: this.format,
+			instance: this
+		});
+		return ast;
+	}
+
+	async transpile(src = this.src) {
+		if (src !== this.src) this.src = src;
+		this._ensurePrepared();
+
+		const ast = await this.parse(src);
+
 		let result = await transpiler({ ast, format: this.format, mapperFile: this.mapperFile, includeDocument: this.includeDocument });
 
 		// 3. Run Transformers
@@ -299,6 +309,8 @@ const lexSync = src => lexer(src);
 
 const parseSync = src => parser(lexer(src));
 
+import { findAndLoadConfig } from "./core/helpers/config-loader.js";
+
 export {
 	HTML,
 	MARKDOWN,
@@ -320,6 +332,7 @@ export {
 	list,
 	parseList,
 	safeArg,
-	todo
+	todo,
+	findAndLoadConfig
 };
 export default SomMark;

package/mappers/mapper.js

@@ -2,7 +2,7 @@ import TagBuilder from "../formatter/tag.js";
 import MarkdownBuilder from "../formatter/mark.js";
 import escapeHTML from "../helpers/escapeHTML.js";
 import { sommarkError } from "../core/errors.js";
-import { matchedValue, safeArg } from "../helpers/utils.js";
+import { matchedValue, safeArg, htmlTable, list, todo } from "../helpers/utils.js";
 
 
 // ========================================================================== //
@@ -33,6 +33,9 @@ class Mapper {
 		this.#customHeaderContent = "";
 
 		this.escapeHTML = escapeHTML;
+		this.htmlTable = htmlTable;
+		this.list = list;
+		this.todo = todo;
 		this.styles = [];
 	}
 
@@ -202,7 +205,6 @@ class Mapper {
 
 			return false;
 		} catch (error) {
-			console.error(error);
 			return false;
 		}
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sommark",
-	"version": "3.3.0",
+	"version": "3.3.2",
 	"description": "SomMark is a declarative, extensible markup language for structured content that can be converted to HTML, Markdown, MDX, JSON, and more.",
 	"main": "index.js",
 	"directories": {

package/test_format_fix.js

@@ -0,0 +1,42 @@
+import SomMark from './index.js';
+
+async function test() {
+    const text = '[Block = attr: "val with space"]\n  Content\n[end]\n';
+    const sm = new SomMark({
+        src: text,
+        format: 'html',
+        plugins: ['sommark-format']
+    });
+    await sm.parse();
+    const formatPlugin = sm.plugins.find(p => p.name === 'sommark-format');
+    const formatted = formatPlugin.formattedSource;
+    console.log("Original:\n", text);
+    console.log("Formatted:\n", formatted);
+    
+    if (formatted.includes('"val with space"')) {
+        console.log("PASS: Quotes preserved for space-containing value.");
+    } else {
+        console.error("FAIL: Quotes LOST!");
+        process.exit(1);
+    }
+    
+    const text2 = 'Text at top level\n(inline)->(bold)\n@_AtBlock_@;\n  content\n@_end_@\n';
+    const sm2 = new SomMark({
+        src: text2,
+        format: 'html',
+        plugins: ['sommark-format']
+    });
+    await sm2.parse();
+    const formatted2 = sm2.plugins.find(p => p.name === 'sommark-format').formattedSource;
+    console.log("Top-level Original:\n", text2);
+    console.log("Top-level Formatted:\n", formatted2);
+    
+    if (formatted2.includes('Text at top level') && formatted2.includes('(inline)->(bold)')) {
+        console.log("PASS: Top-level content preserved.");
+    } else {
+        console.error("FAIL: Top-level content LOST or corrupted!");
+        process.exit(1);
+    }
+}
+
+test();