@fuzdev/fuz_util 0.49.2 → 0.50.0

package/dist/svelte_preprocess_helpers.d.ts

@@ -11,7 +11,7 @@
  *
  * @module
  */
-import type { Expression, ImportDeclaration, ImportDefaultSpecifier, ImportSpecifier } from 'estree';
+import type { Expression, ImportDeclaration, ImportDefaultSpecifier, ImportSpecifier, VariableDeclaration } from 'estree';
 import type { AST } from 'svelte/compiler';
 /** Import metadata for a single import specifier. */
 export interface PreprocessImportInfo {
@@ -67,6 +67,33 @@ export declare const evaluate_static_expr: (expr: Expression, bindings?: Readonl
  * @returns The resolved static string, or `null` if the value is dynamic.
  */
 export declare const extract_static_string: (value: AST.Attribute["value"], bindings?: ReadonlyMap<string, string>) => string | null;
+/** A single branch in a conditional chain extracted from nested ternary expressions. */
+export interface ConditionalChainBranch {
+    /** The source text of the test expression, or `null` for the final else branch. */
+    test_source: string | null;
+    /** The resolved static string value for this branch. */
+    value: string;
+}
+/**
+ * Extracts a chain of conditional expressions where all leaf values are static strings.
+ *
+ * Handles nested ternaries like `a ? 'x' : b ? 'y' : 'z'` by iteratively walking
+ * the right-recursive `ConditionalExpression` chain. At each level, evaluates the
+ * consequent via `evaluate_static_expr` and continues into the alternate if it is
+ * another `ConditionalExpression`. The final alternate is the else branch.
+ *
+ * Returns `null` if the attribute value is not an `ExpressionTag` containing a
+ * `ConditionalExpression`, if any leaf fails to resolve to a static string, or
+ * if the chain exceeds 10 branches (safety limit).
+ *
+ * A 2-branch result covers the simple ternary case (`a ? 'x' : 'y'`).
+ *
+ * @param value The attribute value from `AST.Attribute['value']`.
+ * @param source The full source string (needed to slice test expression source text).
+ * @param bindings Map of variable names to their resolved static string values.
+ * @returns Array of conditional chain branches, or `null` if not extractable.
+ */
+export declare const try_extract_conditional_chain: (value: AST.Attribute["value"], source: string, bindings: ReadonlyMap<string, string>) => Array<ConditionalChainBranch> | null;
 /**
  * Builds a map of statically resolvable `const` bindings from a Svelte AST.
  *
@@ -153,4 +180,70 @@ export declare const has_identifier_in_tree: (node: unknown, name: string, skip?
  * manual escaping is required to match the runtime behavior.
  */
 export declare const escape_svelte_text: (text: string) => string;
+/**
+ * Removes a single-declarator `VariableDeclaration` from source using MagicString.
+ *
+ * Consumes leading whitespace (tabs/spaces) and trailing newline to avoid leaving
+ * blank lines. Only safe for single-declarator statements (`const x = 'val';`);
+ * callers must verify `node.declarations.length === 1` before calling.
+ *
+ * @param s The MagicString instance to modify.
+ * @param declaration_node The `VariableDeclaration` AST node with Svelte position data.
+ * @param source The original source string.
+ */
+export declare const remove_variable_declaration: (s: {
+    remove: (start: number, end: number) => unknown;
+}, declaration_node: VariableDeclaration & {
+    start: number;
+    end: number;
+}, source: string) => void;
+/**
+ * Removes an `ImportDeclaration` from source using MagicString.
+ *
+ * Consumes leading whitespace (tabs/spaces) and trailing newline to avoid leaving
+ * blank lines.
+ *
+ * @param s The MagicString instance to modify.
+ * @param import_node The `ImportDeclaration` AST node with Svelte position data.
+ * @param source The original source string.
+ */
+export declare const remove_import_declaration: (s: {
+    remove: (start: number, end: number) => unknown;
+}, import_node: ImportDeclaration & {
+    start: number;
+    end: number;
+}, source: string) => void;
+/**
+ * Removes a specifier from a multi-specifier import declaration by
+ * reconstructing the statement without the removed specifier.
+ *
+ * Overwrites the entire declaration range to avoid character-level comma surgery.
+ *
+ * Handles:
+ * - `import Mdz, {other} from '...'` → `import {other} from '...'`
+ * - `import {default as Mdz, other} from '...'` → `import {other} from '...'`
+ * - `import {Mdz, other} from '...'` → `import {other} from '...'`
+ *
+ * @param s The MagicString instance to modify.
+ * @param node The positioned `ImportDeclaration` AST node.
+ * @param specifier_to_remove The specifier to remove from the import.
+ * @param source The original source string.
+ * @param additional_lines Extra content appended after the reconstructed import
+ *   (used to bundle new imports into the overwrite to avoid MagicString boundary conflicts).
+ */
+export declare const remove_import_specifier: (s: {
+    overwrite: (start: number, end: number, content: string) => unknown;
+}, node: ImportDeclaration & {
+    start: number;
+    end: number;
+}, specifier_to_remove: ImportDeclaration["specifiers"][number], source: string, additional_lines?: string) => void;
+/**
+ * Handles errors during Svelte preprocessing with configurable behavior.
+ *
+ * @param error The caught error.
+ * @param prefix Log prefix (e.g. `'[fuz-mdz]'`, `'[fuz-code]'`).
+ * @param filename The file being processed.
+ * @param on_error `'throw'` to re-throw as a new Error, `'log'` to console.error.
+ */
+export declare const handle_preprocess_error: (error: unknown, prefix: string, filename: string | undefined, on_error: "throw" | "log") => void;
 //# sourceMappingURL=svelte_preprocess_helpers.d.ts.map

package/dist/svelte_preprocess_helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"svelte_preprocess_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/svelte_preprocess_helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAC,UAAU,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,eAAe,EAAC,MAAM,QAAQ,CAAC;AACnG,OAAO,KAAK,EAAC,GAAG,EAAC,MAAM,iBAAiB,CAAC;AAEzC,qDAAqD;AACrD,MAAM,WAAW,oBAAoB;IACpC,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;CAC1B;AAED,qDAAqD;AACrD,MAAM,WAAW,uBAAuB;IACvC,gEAAgE;IAChE,WAAW,EAAE,iBAAiB,CAAC;IAC/B,mDAAmD;IACnD,SAAS,EAAE,eAAe,GAAG,sBAAsB,CAAC;CACpD;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,GAAG,CAAC,SAAS,EAAE,MAAM,MAAM,KAAG,GAAG,CAAC,SAAS,GAAG,SAOlF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,UAAU,EAChB,WAAW,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,KACpC,MAAM,GAAG,IA+BX,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,GACjC,OAAO,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,EAC7B,WAAW,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,KACpC,MAAM,GAAG,IAkBX,CAAC;AAOF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,GAAI,KAAK,GAAG,CAAC,IAAI,KAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAiBvE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,GACnC,KAAK,GAAG,CAAC,IAAI,EACb,mBAAmB,KAAK,CAAC,MAAM,CAAC,KAC9B,GAAG,CAAC,MAAM,EAAE,uBAAuB,CAcrC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,GAAI,QAAQ,GAAG,CAAC,MAAM,KAAG,MAYhE,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,qBAAqB,GACjC,SAAS,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,EAC1C,SAAQ,MAAa,KACnB,MAyBF,CAAC;AA0BF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,OAAO,EACb,MAAM,MAAM,EACZ,OAAO,GAAG,CAAC,OAAO,CAAC,KACjB,OAgBF,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,MAc/C,CAAC"}
+{"version":3,"file":"svelte_preprocess_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/svelte_preprocess_helpers.ts"],"names":[],"mappings":"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"}

package/dist/svelte_preprocess_helpers.js

@@ -112,6 +112,57 @@ export const extract_static_string = (value, bindings) => {
         return null;
     return evaluate_static_expr(expr, bindings);
 };
+/**
+ * Extracts a chain of conditional expressions where all leaf values are static strings.
+ *
+ * Handles nested ternaries like `a ? 'x' : b ? 'y' : 'z'` by iteratively walking
+ * the right-recursive `ConditionalExpression` chain. At each level, evaluates the
+ * consequent via `evaluate_static_expr` and continues into the alternate if it is
+ * another `ConditionalExpression`. The final alternate is the else branch.
+ *
+ * Returns `null` if the attribute value is not an `ExpressionTag` containing a
+ * `ConditionalExpression`, if any leaf fails to resolve to a static string, or
+ * if the chain exceeds 10 branches (safety limit).
+ *
+ * A 2-branch result covers the simple ternary case (`a ? 'x' : 'y'`).
+ *
+ * @param value The attribute value from `AST.Attribute['value']`.
+ * @param source The full source string (needed to slice test expression source text).
+ * @param bindings Map of variable names to their resolved static string values.
+ * @returns Array of conditional chain branches, or `null` if not extractable.
+ */
+export const try_extract_conditional_chain = (value, source, bindings) => {
+    if (value === true || Array.isArray(value))
+        return null;
+    const expr = value.expression;
+    if (expr.type !== 'ConditionalExpression')
+        return null;
+    const MAX_BRANCHES = 10;
+    const branches = [];
+    let current = expr;
+    for (;;) {
+        const consequent = evaluate_static_expr(current.consequent, bindings);
+        if (consequent === null)
+            return null;
+        const test = current.test;
+        const test_source = source.slice(test.start, test.end);
+        branches.push({ test_source, value: consequent });
+        if (branches.length >= MAX_BRANCHES)
+            return null;
+        if (current.alternate.type === 'ConditionalExpression') {
+            current = current.alternate;
+        }
+        else {
+            // Final else branch
+            const alternate = evaluate_static_expr(current.alternate, bindings);
+            if (alternate === null)
+                return null;
+            branches.push({ test_source: null, value: alternate });
+            break;
+        }
+    }
+    return branches;
+};
 // TODO cross-import tracing: resolve `import {x} from './constants.js'` by reading
 // and parsing the imported module, extracting `export const` values. Would need path
 // resolution ($lib, tsconfig paths), a Program-node variant of this function, and
@@ -330,3 +381,128 @@ export const escape_svelte_text = (text) => text.replace(/[{}<&]/g, (ch) => {
             return ch;
     }
 });
+/**
+ * Removes a single-declarator `VariableDeclaration` from source using MagicString.
+ *
+ * Consumes leading whitespace (tabs/spaces) and trailing newline to avoid leaving
+ * blank lines. Only safe for single-declarator statements (`const x = 'val';`);
+ * callers must verify `node.declarations.length === 1` before calling.
+ *
+ * @param s The MagicString instance to modify.
+ * @param declaration_node The `VariableDeclaration` AST node with Svelte position data.
+ * @param source The original source string.
+ */
+export const remove_variable_declaration = (s, declaration_node, source) => {
+    remove_positioned_node(s, declaration_node, source);
+};
+/**
+ * Removes an `ImportDeclaration` from source using MagicString.
+ *
+ * Consumes leading whitespace (tabs/spaces) and trailing newline to avoid leaving
+ * blank lines.
+ *
+ * @param s The MagicString instance to modify.
+ * @param import_node The `ImportDeclaration` AST node with Svelte position data.
+ * @param source The original source string.
+ */
+export const remove_import_declaration = (s, import_node, source) => {
+    remove_positioned_node(s, import_node, source);
+};
+/**
+ * Removes a positioned AST node from source, consuming surrounding whitespace.
+ *
+ * Consumes leading whitespace (tabs/spaces) and trailing newline to avoid leaving
+ * blank lines. Shared implementation for `remove_variable_declaration` and
+ * `remove_import_declaration`.
+ */
+const remove_positioned_node = (s, node, source) => {
+    let start = node.start;
+    let end = node.end;
+    // Consume trailing newline
+    if (source[end] === '\n') {
+        end++;
+    }
+    else if (source[end] === '\r' && source[end + 1] === '\n') {
+        end += 2;
+    }
+    // Consume leading whitespace on the same line
+    while (start > 0 && (source[start - 1] === '\t' || source[start - 1] === ' ')) {
+        start--;
+    }
+    s.remove(start, end);
+};
+/**
+ * Removes a specifier from a multi-specifier import declaration by
+ * reconstructing the statement without the removed specifier.
+ *
+ * Overwrites the entire declaration range to avoid character-level comma surgery.
+ *
+ * Handles:
+ * - `import Mdz, {other} from '...'` → `import {other} from '...'`
+ * - `import {default as Mdz, other} from '...'` → `import {other} from '...'`
+ * - `import {Mdz, other} from '...'` → `import {other} from '...'`
+ *
+ * @param s The MagicString instance to modify.
+ * @param node The positioned `ImportDeclaration` AST node.
+ * @param specifier_to_remove The specifier to remove from the import.
+ * @param source The original source string.
+ * @param additional_lines Extra content appended after the reconstructed import
+ *   (used to bundle new imports into the overwrite to avoid MagicString boundary conflicts).
+ */
+export const remove_import_specifier = (s, node, specifier_to_remove, source, additional_lines = '') => {
+    const remaining = node.specifiers.filter((spec) => spec !== specifier_to_remove);
+    if (remaining.length === 0)
+        return;
+    const source_path = node.source.value;
+    // Reconstruct the import statement
+    const default_specs = remaining.filter((sp) => sp.type === 'ImportDefaultSpecifier');
+    const named_specs = remaining.filter((sp) => sp.type === 'ImportSpecifier' || sp.type === 'ImportNamespaceSpecifier');
+    let import_clause = '';
+    if (default_specs.length > 0) {
+        import_clause = default_specs[0].local.name;
+        if (named_specs.length > 0) {
+            import_clause += `, {${format_named_specifiers(named_specs)}}`;
+        }
+    }
+    else if (named_specs.length > 0) {
+        import_clause = `{${format_named_specifiers(named_specs)}}`;
+    }
+    const reconstructed = `import ${import_clause} from '${source_path}';`;
+    // Find leading whitespace to preserve indentation
+    let line_start = node.start;
+    while (line_start > 0 && (source[line_start - 1] === '\t' || source[line_start - 1] === ' ')) {
+        line_start--;
+    }
+    const indent = source.slice(line_start, node.start);
+    s.overwrite(line_start, node.end, `${indent}${reconstructed}${additional_lines}`);
+};
+/** Formats named/namespace specifiers as comma-separated string. */
+const format_named_specifiers = (specs) => specs
+    .map((spec) => {
+    if (spec.type === 'ImportNamespaceSpecifier')
+        return `* as ${spec.local.name}`;
+    if (spec.type !== 'ImportSpecifier')
+        return spec.local.name;
+    const imported_name = spec.imported.type === 'Identifier' ? spec.imported.name : spec.imported.value;
+    if (imported_name !== spec.local.name) {
+        return `${imported_name} as ${spec.local.name}`;
+    }
+    return spec.local.name;
+})
+    .join(', ');
+/**
+ * Handles errors during Svelte preprocessing with configurable behavior.
+ *
+ * @param error The caught error.
+ * @param prefix Log prefix (e.g. `'[fuz-mdz]'`, `'[fuz-code]'`).
+ * @param filename The file being processed.
+ * @param on_error `'throw'` to re-throw as a new Error, `'log'` to console.error.
+ */
+export const handle_preprocess_error = (error, prefix, filename, on_error) => {
+    const message = `${prefix} Preprocessing failed${filename ? ` in ${filename}` : ''}: ${error instanceof Error ? error.message : String(error)}`;
+    if (on_error === 'throw') {
+        throw new Error(message, { cause: error });
+    }
+    // eslint-disable-next-line no-console
+    console.error(message);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_util",
-  "version": "0.49.2",
+  "version": "0.50.0",
   "description": "utility belt for JS",
   "glyph": "🦕",
   "logo": "logo.svg",

package/src/lib/svelte_preprocess_helpers.ts

@@ -12,7 +12,14 @@
  * @module
  */
 
-import type {Expression, ImportDeclaration, ImportDefaultSpecifier, ImportSpecifier} from 'estree';
+import type {
+	ConditionalExpression,
+	Expression,
+	ImportDeclaration,
+	ImportDefaultSpecifier,
+	ImportSpecifier,
+	VariableDeclaration,
+} from 'estree';
 import type {AST} from 'svelte/compiler';
 
 /** Import metadata for a single import specifier. */
@@ -136,6 +143,70 @@ export const extract_static_string = (
 	return evaluate_static_expr(expr, bindings);
 };
 
+/** A single branch in a conditional chain extracted from nested ternary expressions. */
+export interface ConditionalChainBranch {
+	/** The source text of the test expression, or `null` for the final else branch. */
+	test_source: string | null;
+	/** The resolved static string value for this branch. */
+	value: string;
+}
+
+/**
+ * Extracts a chain of conditional expressions where all leaf values are static strings.
+ *
+ * Handles nested ternaries like `a ? 'x' : b ? 'y' : 'z'` by iteratively walking
+ * the right-recursive `ConditionalExpression` chain. At each level, evaluates the
+ * consequent via `evaluate_static_expr` and continues into the alternate if it is
+ * another `ConditionalExpression`. The final alternate is the else branch.
+ *
+ * Returns `null` if the attribute value is not an `ExpressionTag` containing a
+ * `ConditionalExpression`, if any leaf fails to resolve to a static string, or
+ * if the chain exceeds 10 branches (safety limit).
+ *
+ * A 2-branch result covers the simple ternary case (`a ? 'x' : 'y'`).
+ *
+ * @param value The attribute value from `AST.Attribute['value']`.
+ * @param source The full source string (needed to slice test expression source text).
+ * @param bindings Map of variable names to their resolved static string values.
+ * @returns Array of conditional chain branches, or `null` if not extractable.
+ */
+export const try_extract_conditional_chain = (
+	value: AST.Attribute['value'],
+	source: string,
+	bindings: ReadonlyMap<string, string>,
+): Array<ConditionalChainBranch> | null => {
+	if (value === true || Array.isArray(value)) return null;
+	const expr = value.expression;
+	if (expr.type !== 'ConditionalExpression') return null;
+
+	const MAX_BRANCHES = 10;
+	const branches: Array<ConditionalChainBranch> = [];
+	let current: ConditionalExpression = expr;
+
+	for (;;) {
+		const consequent = evaluate_static_expr(current.consequent, bindings);
+		if (consequent === null) return null;
+
+		const test = current.test as any;
+		const test_source = source.slice(test.start, test.end);
+		branches.push({test_source, value: consequent});
+
+		if (branches.length >= MAX_BRANCHES) return null;
+
+		if (current.alternate.type === 'ConditionalExpression') {
+			current = current.alternate;
+		} else {
+			// Final else branch
+			const alternate = evaluate_static_expr(current.alternate, bindings);
+			if (alternate === null) return null;
+			branches.push({test_source: null, value: alternate});
+			break;
+		}
+	}
+
+	return branches;
+};
+
 // TODO cross-import tracing: resolve `import {x} from './constants.js'` by reading
 // and parsing the imported module, extracting `export const` values. Would need path
 // resolution ($lib, tsconfig paths), a Program-node variant of this function, and
@@ -364,3 +435,165 @@ export const escape_svelte_text = (text: string): string =>
 				return ch;
 		}
 	});
+
+/**
+ * Removes a single-declarator `VariableDeclaration` from source using MagicString.
+ *
+ * Consumes leading whitespace (tabs/spaces) and trailing newline to avoid leaving
+ * blank lines. Only safe for single-declarator statements (`const x = 'val';`);
+ * callers must verify `node.declarations.length === 1` before calling.
+ *
+ * @param s The MagicString instance to modify.
+ * @param declaration_node The `VariableDeclaration` AST node with Svelte position data.
+ * @param source The original source string.
+ */
+export const remove_variable_declaration = (
+	s: {remove: (start: number, end: number) => unknown},
+	declaration_node: VariableDeclaration & {start: number; end: number},
+	source: string,
+): void => {
+	remove_positioned_node(s, declaration_node, source);
+};
+
+/**
+ * Removes an `ImportDeclaration` from source using MagicString.
+ *
+ * Consumes leading whitespace (tabs/spaces) and trailing newline to avoid leaving
+ * blank lines.
+ *
+ * @param s The MagicString instance to modify.
+ * @param import_node The `ImportDeclaration` AST node with Svelte position data.
+ * @param source The original source string.
+ */
+export const remove_import_declaration = (
+	s: {remove: (start: number, end: number) => unknown},
+	import_node: ImportDeclaration & {start: number; end: number},
+	source: string,
+): void => {
+	remove_positioned_node(s, import_node, source);
+};
+
+/**
+ * Removes a positioned AST node from source, consuming surrounding whitespace.
+ *
+ * Consumes leading whitespace (tabs/spaces) and trailing newline to avoid leaving
+ * blank lines. Shared implementation for `remove_variable_declaration` and
+ * `remove_import_declaration`.
+ */
+const remove_positioned_node = (
+	s: {remove: (start: number, end: number) => unknown},
+	node: {start: number; end: number},
+	source: string,
+): void => {
+	let start: number = node.start;
+	let end: number = node.end;
+
+	// Consume trailing newline
+	if (source[end] === '\n') {
+		end++;
+	} else if (source[end] === '\r' && source[end + 1] === '\n') {
+		end += 2;
+	}
+
+	// Consume leading whitespace on the same line
+	while (start > 0 && (source[start - 1] === '\t' || source[start - 1] === ' ')) {
+		start--;
+	}
+
+	s.remove(start, end);
+};
+
+/**
+ * Removes a specifier from a multi-specifier import declaration by
+ * reconstructing the statement without the removed specifier.
+ *
+ * Overwrites the entire declaration range to avoid character-level comma surgery.
+ *
+ * Handles:
+ * - `import Mdz, {other} from '...'` → `import {other} from '...'`
+ * - `import {default as Mdz, other} from '...'` → `import {other} from '...'`
+ * - `import {Mdz, other} from '...'` → `import {other} from '...'`
+ *
+ * @param s The MagicString instance to modify.
+ * @param node The positioned `ImportDeclaration` AST node.
+ * @param specifier_to_remove The specifier to remove from the import.
+ * @param source The original source string.
+ * @param additional_lines Extra content appended after the reconstructed import
+ *   (used to bundle new imports into the overwrite to avoid MagicString boundary conflicts).
+ */
+export const remove_import_specifier = (
+	s: {overwrite: (start: number, end: number, content: string) => unknown},
+	node: ImportDeclaration & {start: number; end: number},
+	specifier_to_remove: ImportDeclaration['specifiers'][number],
+	source: string,
+	additional_lines: string = '',
+): void => {
+	const remaining = node.specifiers.filter((spec) => spec !== specifier_to_remove);
+	if (remaining.length === 0) return;
+
+	const source_path = node.source.value as string;
+
+	// Reconstruct the import statement
+	const default_specs = remaining.filter((sp) => sp.type === 'ImportDefaultSpecifier');
+	const named_specs = remaining.filter(
+		(sp) => sp.type === 'ImportSpecifier' || sp.type === 'ImportNamespaceSpecifier',
+	);
+
+	let import_clause = '';
+	if (default_specs.length > 0) {
+		import_clause = default_specs[0]!.local.name;
+		if (named_specs.length > 0) {
+			import_clause += `, {${format_named_specifiers(named_specs)}}`;
+		}
+	} else if (named_specs.length > 0) {
+		import_clause = `{${format_named_specifiers(named_specs)}}`;
+	}
+
+	const reconstructed = `import ${import_clause} from '${source_path}';`;
+
+	// Find leading whitespace to preserve indentation
+	let line_start = node.start;
+	while (line_start > 0 && (source[line_start - 1] === '\t' || source[line_start - 1] === ' ')) {
+		line_start--;
+	}
+	const indent = source.slice(line_start, node.start);
+
+	s.overwrite(line_start, node.end, `${indent}${reconstructed}${additional_lines}`);
+};
+
+/** Formats named/namespace specifiers as comma-separated string. */
+const format_named_specifiers = (specs: Array<ImportDeclaration['specifiers'][number]>): string =>
+	specs
+		.map((spec) => {
+			if (spec.type === 'ImportNamespaceSpecifier') return `* as ${spec.local.name}`;
+			if (spec.type !== 'ImportSpecifier') return spec.local.name;
+			const imported_name =
+				spec.imported.type === 'Identifier' ? spec.imported.name : spec.imported.value;
+			if (imported_name !== spec.local.name) {
+				return `${imported_name} as ${spec.local.name}`;
+			}
+			return spec.local.name;
+		})
+		.join(', ');
+
+/**
+ * Handles errors during Svelte preprocessing with configurable behavior.
+ *
+ * @param error The caught error.
+ * @param prefix Log prefix (e.g. `'[fuz-mdz]'`, `'[fuz-code]'`).
+ * @param filename The file being processed.
+ * @param on_error `'throw'` to re-throw as a new Error, `'log'` to console.error.
+ */
+export const handle_preprocess_error = (
+	error: unknown,
+	prefix: string,
+	filename: string | undefined,
+	on_error: 'throw' | 'log',
+): void => {
+	const message = `${prefix} Preprocessing failed${filename ? ` in ${filename}` : ''}: ${error instanceof Error ? error.message : String(error)}`;
+	if (on_error === 'throw') {
+		throw new Error(message, {cause: error});
+	}
+	// eslint-disable-next-line no-console
+	console.error(message);
+};