@fuzdev/fuz_util 0.48.4 → 0.49.0

package/dist/diff.js

@@ -3,7 +3,7 @@
  *
  * @module
  */
-import { is_binary } from './string.js';
+import { string_is_binary } from './string.js';
 /**
  * Generate a line-based diff between two strings using LCS algorithm.
  *
@@ -176,7 +176,7 @@ export const format_diff = (diff, current_path, desired_path, options = {}) => {
  */
 export const generate_diff = (current, desired, path, options = {}) => {
     // Skip binary files
-    if (is_binary(current) || is_binary(desired)) {
+    if (string_is_binary(current) || string_is_binary(desired)) {
         return null;
     }
     const diff = diff_lines(current, desired);

package/dist/path.d.ts

@@ -53,6 +53,17 @@ export type PathPiece = {
  * @todo maybe rethink this API, it's a bit weird, but fits the usage in `ui/Breadcrumbs.svelte`
  */
 export declare const parse_path_pieces: (raw_path: string) => Array<PathPiece>;
+/**
+ * Checks if a filename matches any exclusion pattern.
+ *
+ * Returns `false` when `filename` is `undefined`, empty string, or `exclude` is empty.
+ * String patterns use substring matching. RegExp patterns use `.test()`.
+ *
+ * @param filename The file path to check, or `undefined` for virtual files.
+ * @param exclude Array of string or RegExp exclusion patterns.
+ * @returns `true` if the file should be excluded from processing.
+ */
+export declare const should_exclude_path: (filename: string | undefined, exclude: Array<string | RegExp>) => boolean;
 /**
  * Converts a string into a URL-compatible slug.
  * @param str the string to convert

package/dist/path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AAEzC;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC7C,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,KAAK,OAAO,CAAC;AAE1E;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,aAAa,MAAM,GAAG,GAAG,KAAG,MACgC,CAAC;AAE1F;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,KAAK,CAAC,MAAM,CAU3D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,KAAG,KAAK,CAAC,MAAM,CACH,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,SAAS,GAClB;IACA,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACZ,GACD;IACA,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACZ,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,KAAG,KAAK,CAAC,SAAS,CAgBnE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,EAAE,gCAA6B,KAAG,MAYpE,CAAC"}
+{"version":3,"file":"path.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AAEzC;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC7C,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,KAAK,OAAO,CAAC;AAE1E;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,aAAa,MAAM,GAAG,GAAG,KAAG,MACgC,CAAC;AAE1F;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,KAAK,CAAC,MAAM,CAU3D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,KAAG,KAAK,CAAC,MAAM,CACH,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,SAAS,GAClB;IACA,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACZ,GACD;IACA,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACZ,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,KAAG,KAAK,CAAC,SAAS,CAgBnE,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAC/B,UAAU,MAAM,GAAG,SAAS,EAC5B,SAAS,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,KAC7B,OAKF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,EAAE,gCAA6B,KAAG,MAYpE,CAAC"}

package/dist/path.js

@@ -42,6 +42,21 @@ export const parse_path_pieces = (raw_path) => {
     }
     return pieces;
 };
+/**
+ * Checks if a filename matches any exclusion pattern.
+ *
+ * Returns `false` when `filename` is `undefined`, empty string, or `exclude` is empty.
+ * String patterns use substring matching. RegExp patterns use `.test()`.
+ *
+ * @param filename The file path to check, or `undefined` for virtual files.
+ * @param exclude Array of string or RegExp exclusion patterns.
+ * @returns `true` if the file should be excluded from processing.
+ */
+export const should_exclude_path = (filename, exclude) => {
+    if (!filename || exclude.length === 0)
+        return false;
+    return exclude.some((pattern) => typeof pattern === 'string' ? filename.includes(pattern) : pattern.test(filename));
+};
 /**
  * Converts a string into a URL-compatible slug.
  * @param str the string to convert

package/dist/string.d.ts

@@ -70,6 +70,13 @@ export declare const pad_width: (str: string, target_width: number, align?: "lef
  * @returns The edit distance between the strings
  */
 export declare const levenshtein_distance: (a: string, b: string) => number;
+/**
+ * Escapes a string for use inside a single-quoted JS string literal.
+ *
+ * Uses a single-pass regex replacement to escape backslashes, single quotes,
+ * newlines, carriage returns, and Unicode line/paragraph separators.
+ */
+export declare const escape_js_string: (value: string) => string;
 /**
  * Check if content appears to be binary.
  *
@@ -78,5 +85,5 @@ export declare const levenshtein_distance: (a: string, b: string) => number;
  * @param content - Content to check.
  * @returns True if content appears to be binary.
  */
-export declare const is_binary: (content: string) => boolean;
+export declare const string_is_binary: (content: string) => boolean;
 //# sourceMappingURL=string.d.ts.map

package/dist/string.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"string.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/string.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,EAAE,WAAW,MAAM,EAAE,eAAc,KAAG,MAMzE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAG9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAG5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAK9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAK/D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,MAG9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,MAG5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,KAAG,MAK1B,CAAC;AAEd;;GAEG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,eAAY,KAAG,MAC9C,CAAC;AAE3B;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,KAAG,MACI,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,MAAsD,CAAC;AAEhG;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,MACwC,CAAC;AAEpF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,MAAM,KAAG,MAuClD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS,GACrB,KAAK,MAAM,EACX,cAAc,MAAM,EACpB,QAAO,MAAM,GAAG,OAAgB,KAC9B,MAQF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,MAmC3D,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,MAAM,KAAG,OAG3C,CAAC"}
+{"version":3,"file":"string.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/string.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,EAAE,WAAW,MAAM,EAAE,eAAc,KAAG,MAMzE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAG9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAG5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAK9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAK/D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,MAG9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,MAG5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,KAAG,MAK1B,CAAC;AAEd;;GAEG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,eAAY,KAAG,MAC9C,CAAC;AAE3B;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,KAAG,MACI,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,MAAsD,CAAC;AAEhG;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,MACwC,CAAC;AAEpF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,MAAM,KAAG,MAuClD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS,GACrB,KAAK,MAAM,EACX,cAAc,MAAM,EACpB,QAAO,MAAM,GAAG,OAAgB,KAC9B,MAQF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,MAmC3D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,KAAG,MAkB9C,CAAC;AAEJ;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,MAAM,KAAG,OAAgD,CAAC"}

package/dist/string.js

@@ -191,6 +191,30 @@ export const levenshtein_distance = (a, b) => {
     }
     return prev[short_len];
 };
+/**
+ * Escapes a string for use inside a single-quoted JS string literal.
+ *
+ * Uses a single-pass regex replacement to escape backslashes, single quotes,
+ * newlines, carriage returns, and Unicode line/paragraph separators.
+ */
+export const escape_js_string = (value) => value.replace(/[\\'\n\r\u2028\u2029]/g, (ch) => {
+    switch (ch) {
+        case '\\':
+            return '\\\\';
+        case "'":
+            return "\\'";
+        case '\n':
+            return '\\n';
+        case '\r':
+            return '\\r';
+        case '\u2028':
+            return '\\u2028';
+        case '\u2029':
+            return '\\u2029';
+        default:
+            return ch;
+    }
+});
 /**
  * Check if content appears to be binary.
  *
@@ -199,7 +223,4 @@ export const levenshtein_distance = (a, b) => {
  * @param content - Content to check.
  * @returns True if content appears to be binary.
  */
-export const is_binary = (content) => {
-    const sample = content.slice(0, 8192);
-    return sample.includes('\0');
-};
+export const string_is_binary = (content) => content.slice(0, 8192).includes('\0');

package/dist/svelte_preprocess_helpers.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Shared helper functions for Svelte preprocessors.
+ *
+ * Provides AST utilities for detecting static content, resolving imports,
+ * managing import statements, and escaping strings for Svelte templates.
+ * Used by `svelte_preprocess_mdz` in fuz_ui, `svelte_preprocess_fuz_code`
+ * in fuz_code, and potentially other Svelte preprocessors.
+ *
+ * Uses `import type` from `svelte/compiler` for AST types only — no runtime
+ * Svelte dependency. Consumers must have `svelte` installed for type resolution.
+ *
+ * @module
+ */
+import type { Expression, ImportDeclaration, ImportDefaultSpecifier, ImportSpecifier } from 'estree';
+import type { AST } from 'svelte/compiler';
+/** Import metadata for a single import specifier. */
+export interface PreprocessImportInfo {
+    /** The module path to import from. */
+    path: string;
+    /** Whether this is a default or named import. */
+    kind: 'default' | 'named';
+}
+/** Information about a resolved component import. */
+export interface ResolvedComponentImport {
+    /** The `ImportDeclaration` AST node that provides this name. */
+    import_node: ImportDeclaration;
+    /** The specific import specifier for this name. */
+    specifier: ImportSpecifier | ImportDefaultSpecifier;
+}
+/**
+ * Finds an attribute by name on a component AST node.
+ *
+ * Iterates the node's `attributes` array and returns the first `Attribute`
+ * node whose `name` matches. Skips `SpreadAttribute`, directive, and other node types.
+ *
+ * @param node The component AST node to search.
+ * @param name The attribute name to find.
+ * @returns The matching `Attribute` node, or `undefined` if not found.
+ */
+export declare const find_attribute: (node: AST.Component, name: string) => AST.Attribute | undefined;
+/**
+ * Recursively evaluates an expression AST node to a static string value.
+ *
+ * Handles string `Literal`, `TemplateLiteral` without interpolation, and
+ * `BinaryExpression` with the `+` operator (string concatenation).
+ * Returns `null` for dynamic expressions, non-string literals, or unsupported node types.
+ *
+ * @param expr An ESTree expression AST node.
+ * @returns The resolved static string, or `null` if the expression is dynamic.
+ */
+export declare const evaluate_static_expr: (expr: Expression) => string | null;
+/**
+ * Extracts a static string value from a Svelte attribute value AST node.
+ *
+ * Handles three forms:
+ * - Boolean `true` (bare attribute like `inline`) -- returns `null`.
+ * - Array with a single `Text` node (quoted attribute like `content="text"`) --
+ *   returns the text data.
+ * - `ExpressionTag` (expression like `content={'text'}`) -- delegates to `evaluate_static_expr`.
+ *
+ * Returns `null` for null literals, mixed arrays, dynamic expressions, and non-string values.
+ *
+ * @param value The attribute value from `AST.Attribute['value']`.
+ * @returns The resolved static string, or `null` if the value is dynamic.
+ */
+export declare const extract_static_string: (value: AST.Attribute["value"]) => string | null;
+/**
+ * Resolves local names that import from specified source paths.
+ *
+ * Scans `ImportDeclaration` nodes in both the instance and module scripts.
+ * Handles default, named, and aliased imports. Skips namespace imports.
+ * Returns import node references alongside names to support import removal.
+ *
+ * @param ast The parsed Svelte AST root node.
+ * @param component_imports Array of import source paths to match against.
+ * @returns Map of local names to their resolved import info.
+ */
+export declare const resolve_component_names: (ast: AST.Root, component_imports: Array<string>) => Map<string, ResolvedComponentImport>;
+/**
+ * Finds the position to insert new import statements within a script block.
+ *
+ * Returns the end position of the last `ImportDeclaration`, or the start
+ * of the script body content if no imports exist.
+ *
+ * @param script The parsed `AST.Script` node.
+ * @returns The character position where new imports should be inserted.
+ */
+export declare const find_import_insert_position: (script: AST.Script) => number;
+/**
+ * Generates indented import statement lines from an import map.
+ *
+ * Default imports produce `import Name from 'path';` lines.
+ * Named imports are grouped by path into `import {a, b} from 'path';` lines.
+ *
+ * @param imports Map of local names to their import info.
+ * @param indent Indentation prefix for each line. @default '\t'
+ * @returns A string of newline-separated import statements.
+ */
+export declare const generate_import_lines: (imports: Map<string, PreprocessImportInfo>, indent?: string) => string;
+/**
+ * Checks if an identifier with the given name appears anywhere in an AST subtree.
+ *
+ * Recursively walks all object and array properties of the tree, matching
+ * ESTree `Identifier` nodes (`{type: 'Identifier', name}`). Nodes in the
+ * `skip` set are excluded from traversal — used to skip `ImportDeclaration`
+ * nodes so the import's own specifier identifier doesn't false-positive.
+ *
+ * Safe for Svelte template ASTs: `Component.name` is a plain string property
+ * (not an `Identifier` node), so `<Mdz>` tags do not produce false matches.
+ *
+ * @param node The AST subtree to search.
+ * @param name The identifier name to look for.
+ * @param skip Set of AST nodes to skip during traversal.
+ * @returns `true` if a matching `Identifier` node is found.
+ */
+export declare const has_identifier_in_tree: (node: unknown, name: string, skip?: Set<unknown>) => boolean;
+/**
+ * Escapes text for safe embedding in Svelte template markup.
+ *
+ * Uses a single-pass regex replacement to avoid corruption that occurs with sequential
+ * `.replace()` calls (where the second replace matches characters introduced by the first).
+ *
+ * Escapes four characters:
+ * - `{` → `{'{'}` and `}` → `{'}'}` — prevents Svelte expression interpretation
+ * - `<` → `&lt;` — prevents HTML/Svelte tag interpretation
+ * - `&` → `&amp;` — prevents HTML entity interpretation
+ *
+ * The `&` escaping is necessary because runtime `MdzNodeView.svelte` renders text
+ * with `{node.content}` (a Svelte expression), which auto-escapes `&` to `&amp;`.
+ * The preprocessor emits raw template text where `&` is NOT auto-escaped, so
+ * manual escaping is required to match the runtime behavior.
+ */
+export declare const escape_svelte_text: (text: string) => string;
+//# sourceMappingURL=svelte_preprocess_helpers.d.ts.map

package/dist/svelte_preprocess_helpers.d.ts.map

@@ -0,0 +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;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,UAAU,KAAG,MAAM,GAAG,IAchE,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,GAAI,OAAO,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,KAAG,MAAM,GAAG,IAkB9E,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;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,OAAO,EACb,MAAM,MAAM,EACZ,OAAO,GAAG,CAAC,OAAO,CAAC,KACjB,OAYF,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,MAc/C,CAAC"}

package/dist/svelte_preprocess_helpers.js

@@ -0,0 +1,243 @@
+/**
+ * Shared helper functions for Svelte preprocessors.
+ *
+ * Provides AST utilities for detecting static content, resolving imports,
+ * managing import statements, and escaping strings for Svelte templates.
+ * Used by `svelte_preprocess_mdz` in fuz_ui, `svelte_preprocess_fuz_code`
+ * in fuz_code, and potentially other Svelte preprocessors.
+ *
+ * Uses `import type` from `svelte/compiler` for AST types only — no runtime
+ * Svelte dependency. Consumers must have `svelte` installed for type resolution.
+ *
+ * @module
+ */
+/**
+ * Finds an attribute by name on a component AST node.
+ *
+ * Iterates the node's `attributes` array and returns the first `Attribute`
+ * node whose `name` matches. Skips `SpreadAttribute`, directive, and other node types.
+ *
+ * @param node The component AST node to search.
+ * @param name The attribute name to find.
+ * @returns The matching `Attribute` node, or `undefined` if not found.
+ */
+export const find_attribute = (node, name) => {
+    for (const attr of node.attributes) {
+        if (attr.type === 'Attribute' && attr.name === name) {
+            return attr;
+        }
+    }
+    return undefined;
+};
+/**
+ * Recursively evaluates an expression AST node to a static string value.
+ *
+ * Handles string `Literal`, `TemplateLiteral` without interpolation, and
+ * `BinaryExpression` with the `+` operator (string concatenation).
+ * Returns `null` for dynamic expressions, non-string literals, or unsupported node types.
+ *
+ * @param expr An ESTree expression AST node.
+ * @returns The resolved static string, or `null` if the expression is dynamic.
+ */
+export const evaluate_static_expr = (expr) => {
+    if (expr.type === 'Literal' && typeof expr.value === 'string')
+        return expr.value;
+    if (expr.type === 'TemplateLiteral' && expr.expressions.length === 0) {
+        return expr.quasis.map((q) => q.value.cooked ?? q.value.raw).join('');
+    }
+    if (expr.type === 'BinaryExpression' && expr.operator === '+') {
+        if (expr.left.type === 'PrivateIdentifier')
+            return null;
+        const left = evaluate_static_expr(expr.left);
+        if (left === null)
+            return null;
+        const right = evaluate_static_expr(expr.right);
+        if (right === null)
+            return null;
+        return left + right;
+    }
+    return null;
+};
+/**
+ * Extracts a static string value from a Svelte attribute value AST node.
+ *
+ * Handles three forms:
+ * - Boolean `true` (bare attribute like `inline`) -- returns `null`.
+ * - Array with a single `Text` node (quoted attribute like `content="text"`) --
+ *   returns the text data.
+ * - `ExpressionTag` (expression like `content={'text'}`) -- delegates to `evaluate_static_expr`.
+ *
+ * Returns `null` for null literals, mixed arrays, dynamic expressions, and non-string values.
+ *
+ * @param value The attribute value from `AST.Attribute['value']`.
+ * @returns The resolved static string, or `null` if the value is dynamic.
+ */
+export const extract_static_string = (value) => {
+    // Boolean attribute (e.g., <Mdz inline />)
+    if (value === true)
+        return null;
+    // Plain attribute: content="text"
+    if (Array.isArray(value)) {
+        const first = value[0];
+        if (value.length === 1 && first?.type === 'Text') {
+            return first.data;
+        }
+        return null;
+    }
+    // ExpressionTag: content={expr}
+    const expr = value.expression;
+    // Null literal
+    if (expr.type === 'Literal' && expr.value === null)
+        return null;
+    return evaluate_static_expr(expr);
+};
+/**
+ * Resolves local names that import from specified source paths.
+ *
+ * Scans `ImportDeclaration` nodes in both the instance and module scripts.
+ * Handles default, named, and aliased imports. Skips namespace imports.
+ * Returns import node references alongside names to support import removal.
+ *
+ * @param ast The parsed Svelte AST root node.
+ * @param component_imports Array of import source paths to match against.
+ * @returns Map of local names to their resolved import info.
+ */
+export const resolve_component_names = (ast, component_imports) => {
+    const names = new Map();
+    for (const script of [ast.instance, ast.module]) {
+        if (!script)
+            continue;
+        for (const node of script.content.body) {
+            if (node.type !== 'ImportDeclaration')
+                continue;
+            if (!component_imports.includes(node.source.value))
+                continue;
+            for (const specifier of node.specifiers) {
+                if (specifier.type === 'ImportNamespaceSpecifier')
+                    continue;
+                names.set(specifier.local.name, { import_node: node, specifier });
+            }
+        }
+    }
+    return names;
+};
+/**
+ * Finds the position to insert new import statements within a script block.
+ *
+ * Returns the end position of the last `ImportDeclaration`, or the start
+ * of the script body content if no imports exist.
+ *
+ * @param script The parsed `AST.Script` node.
+ * @returns The character position where new imports should be inserted.
+ */
+export const find_import_insert_position = (script) => {
+    let last_import_end = -1;
+    for (const node of script.content.body) {
+        if (node.type === 'ImportDeclaration') {
+            // Svelte's parser always provides position data on AST nodes
+            last_import_end = node.end;
+        }
+    }
+    if (last_import_end !== -1) {
+        return last_import_end;
+    }
+    return script.content.start;
+};
+/**
+ * Generates indented import statement lines from an import map.
+ *
+ * Default imports produce `import Name from 'path';` lines.
+ * Named imports are grouped by path into `import {a, b} from 'path';` lines.
+ *
+ * @param imports Map of local names to their import info.
+ * @param indent Indentation prefix for each line. @default '\t'
+ * @returns A string of newline-separated import statements.
+ */
+export const generate_import_lines = (imports, indent = '\t') => {
+    const default_imports = [];
+    const named_by_path = new Map();
+    for (const [name, { path, kind }] of imports) {
+        if (kind === 'default') {
+            default_imports.push([name, path]);
+        }
+        else {
+            let names = named_by_path.get(path);
+            if (!names) {
+                names = [];
+                named_by_path.set(path, names);
+            }
+            names.push(name);
+        }
+    }
+    const lines = [];
+    for (const [name, path] of default_imports) {
+        lines.push(`${indent}import ${name} from '${path}';`);
+    }
+    for (const [path, names] of named_by_path) {
+        lines.push(`${indent}import {${names.join(', ')}} from '${path}';`);
+    }
+    return lines.join('\n');
+};
+/**
+ * Checks if an identifier with the given name appears anywhere in an AST subtree.
+ *
+ * Recursively walks all object and array properties of the tree, matching
+ * ESTree `Identifier` nodes (`{type: 'Identifier', name}`). Nodes in the
+ * `skip` set are excluded from traversal — used to skip `ImportDeclaration`
+ * nodes so the import's own specifier identifier doesn't false-positive.
+ *
+ * Safe for Svelte template ASTs: `Component.name` is a plain string property
+ * (not an `Identifier` node), so `<Mdz>` tags do not produce false matches.
+ *
+ * @param node The AST subtree to search.
+ * @param name The identifier name to look for.
+ * @param skip Set of AST nodes to skip during traversal.
+ * @returns `true` if a matching `Identifier` node is found.
+ */
+export const has_identifier_in_tree = (node, name, skip) => {
+    if (node === null || node === undefined || typeof node !== 'object')
+        return false;
+    if (skip?.has(node))
+        return false;
+    if (Array.isArray(node)) {
+        return node.some((child) => has_identifier_in_tree(child, name, skip));
+    }
+    const record = node;
+    if (record.type === 'Identifier' && record.name === name)
+        return true;
+    for (const key of Object.keys(record)) {
+        if (has_identifier_in_tree(record[key], name, skip))
+            return true;
+    }
+    return false;
+};
+/**
+ * Escapes text for safe embedding in Svelte template markup.
+ *
+ * Uses a single-pass regex replacement to avoid corruption that occurs with sequential
+ * `.replace()` calls (where the second replace matches characters introduced by the first).
+ *
+ * Escapes four characters:
+ * - `{` → `{'{'}` and `}` → `{'}'}` — prevents Svelte expression interpretation
+ * - `<` → `&lt;` — prevents HTML/Svelte tag interpretation
+ * - `&` → `&amp;` — prevents HTML entity interpretation
+ *
+ * The `&` escaping is necessary because runtime `MdzNodeView.svelte` renders text
+ * with `{node.content}` (a Svelte expression), which auto-escapes `&` to `&amp;`.
+ * The preprocessor emits raw template text where `&` is NOT auto-escaped, so
+ * manual escaping is required to match the runtime behavior.
+ */
+export const escape_svelte_text = (text) => text.replace(/[{}<&]/g, (ch) => {
+    switch (ch) {
+        case '{':
+            return "{'{'}";
+        case '}':
+            return "{'}'}";
+        case '<':
+            return '&lt;';
+        case '&':
+            return '&amp;';
+        default:
+            return ch;
+    }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_util",
-  "version": "0.48.4",
+  "version": "0.49.0",
   "description": "utility belt for JS",
   "glyph": "🦕",
   "logo": "logo.svg",
@@ -44,8 +44,10 @@
     "web"
   ],
   "peerDependencies": {
+    "@types/estree": "^1",
     "@types/node": "^24",
     "esm-env": "^1.2.2",
+    "svelte": "^5",
     "zod": "^4.0.14"
   },
   "peerDependenciesMeta": {
@@ -55,6 +57,12 @@
     "esm-env": {
       "optional": true
     },
+    "@types/estree": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    },
     "zod": {
       "optional": true
     }
@@ -70,6 +78,7 @@
     "@sveltejs/kit": "^2.50.1",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@types/estree": "^1.0.8",
     "@types/node": "^24.10.1",
     "@webref/css": "^8.2.0",
     "dequal": "^2.0.3",

package/src/lib/diff.ts

@@ -4,7 +4,7 @@
  * @module
  */
 
-import {is_binary} from './string.js';
+import {string_is_binary} from './string.js';
 
 /** Line diff result */
 export interface DiffLine {
@@ -224,7 +224,7 @@ export const generate_diff = (
 	options: FormatDiffOptions = {},
 ): string | null => {
 	// Skip binary files
-	if (is_binary(current) || is_binary(desired)) {
+	if (string_is_binary(current) || string_is_binary(desired)) {
 		return null;
 	}
 

package/src/lib/path.ts

@@ -94,6 +94,26 @@ export const parse_path_pieces = (raw_path: string): Array<PathPiece> => {
 	return pieces;
 };
 
+/**
+ * Checks if a filename matches any exclusion pattern.
+ *
+ * Returns `false` when `filename` is `undefined`, empty string, or `exclude` is empty.
+ * String patterns use substring matching. RegExp patterns use `.test()`.
+ *
+ * @param filename The file path to check, or `undefined` for virtual files.
+ * @param exclude Array of string or RegExp exclusion patterns.
+ * @returns `true` if the file should be excluded from processing.
+ */
+export const should_exclude_path = (
+	filename: string | undefined,
+	exclude: Array<string | RegExp>,
+): boolean => {
+	if (!filename || exclude.length === 0) return false;
+	return exclude.some((pattern) =>
+		typeof pattern === 'string' ? filename.includes(pattern) : pattern.test(filename),
+	);
+};
+
 /**
  * Converts a string into a URL-compatible slug.
  * @param str the string to convert

package/src/lib/string.ts

@@ -209,6 +209,32 @@ export const levenshtein_distance = (a: string, b: string): number => {
 	return prev[short_len]!;
 };
 
+/**
+ * Escapes a string for use inside a single-quoted JS string literal.
+ *
+ * Uses a single-pass regex replacement to escape backslashes, single quotes,
+ * newlines, carriage returns, and Unicode line/paragraph separators.
+ */
+export const escape_js_string = (value: string): string =>
+	value.replace(/[\\'\n\r\u2028\u2029]/g, (ch) => {
+		switch (ch) {
+			case '\\':
+				return '\\\\';
+			case "'":
+				return "\\'";
+			case '\n':
+				return '\\n';
+			case '\r':
+				return '\\r';
+			case '\u2028':
+				return '\\u2028';
+			case '\u2029':
+				return '\\u2029';
+			default:
+				return ch;
+		}
+	});
+
 /**
  * Check if content appears to be binary.
  *
@@ -217,7 +243,4 @@ export const levenshtein_distance = (a: string, b: string): number => {
  * @param content - Content to check.
  * @returns True if content appears to be binary.
  */
-export const is_binary = (content: string): boolean => {
-	const sample = content.slice(0, 8192);
-	return sample.includes('\0');
-};
+export const string_is_binary = (content: string): boolean => content.slice(0, 8192).includes('\0');

package/src/lib/svelte_preprocess_helpers.ts

@@ -0,0 +1,270 @@
+/**
+ * Shared helper functions for Svelte preprocessors.
+ *
+ * Provides AST utilities for detecting static content, resolving imports,
+ * managing import statements, and escaping strings for Svelte templates.
+ * Used by `svelte_preprocess_mdz` in fuz_ui, `svelte_preprocess_fuz_code`
+ * in fuz_code, and potentially other Svelte preprocessors.
+ *
+ * Uses `import type` from `svelte/compiler` for AST types only — no runtime
+ * Svelte dependency. Consumers must have `svelte` installed for type resolution.
+ *
+ * @module
+ */
+
+import type {Expression, ImportDeclaration, ImportDefaultSpecifier, ImportSpecifier} from 'estree';
+import type {AST} from 'svelte/compiler';
+
+/** Import metadata for a single import specifier. */
+export interface PreprocessImportInfo {
+	/** The module path to import from. */
+	path: string;
+	/** Whether this is a default or named import. */
+	kind: 'default' | 'named';
+}
+
+/** Information about a resolved component import. */
+export interface ResolvedComponentImport {
+	/** The `ImportDeclaration` AST node that provides this name. */
+	import_node: ImportDeclaration;
+	/** The specific import specifier for this name. */
+	specifier: ImportSpecifier | ImportDefaultSpecifier;
+}
+
+/**
+ * Finds an attribute by name on a component AST node.
+ *
+ * Iterates the node's `attributes` array and returns the first `Attribute`
+ * node whose `name` matches. Skips `SpreadAttribute`, directive, and other node types.
+ *
+ * @param node The component AST node to search.
+ * @param name The attribute name to find.
+ * @returns The matching `Attribute` node, or `undefined` if not found.
+ */
+export const find_attribute = (node: AST.Component, name: string): AST.Attribute | undefined => {
+	for (const attr of node.attributes) {
+		if (attr.type === 'Attribute' && attr.name === name) {
+			return attr;
+		}
+	}
+	return undefined;
+};
+
+/**
+ * Recursively evaluates an expression AST node to a static string value.
+ *
+ * Handles string `Literal`, `TemplateLiteral` without interpolation, and
+ * `BinaryExpression` with the `+` operator (string concatenation).
+ * Returns `null` for dynamic expressions, non-string literals, or unsupported node types.
+ *
+ * @param expr An ESTree expression AST node.
+ * @returns The resolved static string, or `null` if the expression is dynamic.
+ */
+export const evaluate_static_expr = (expr: Expression): string | null => {
+	if (expr.type === 'Literal' && typeof expr.value === 'string') return expr.value;
+	if (expr.type === 'TemplateLiteral' && expr.expressions.length === 0) {
+		return expr.quasis.map((q) => q.value.cooked ?? q.value.raw).join('');
+	}
+	if (expr.type === 'BinaryExpression' && expr.operator === '+') {
+		if (expr.left.type === 'PrivateIdentifier') return null;
+		const left = evaluate_static_expr(expr.left);
+		if (left === null) return null;
+		const right = evaluate_static_expr(expr.right);
+		if (right === null) return null;
+		return left + right;
+	}
+	return null;
+};
+
+/**
+ * Extracts a static string value from a Svelte attribute value AST node.
+ *
+ * Handles three forms:
+ * - Boolean `true` (bare attribute like `inline`) -- returns `null`.
+ * - Array with a single `Text` node (quoted attribute like `content="text"`) --
+ *   returns the text data.
+ * - `ExpressionTag` (expression like `content={'text'}`) -- delegates to `evaluate_static_expr`.
+ *
+ * Returns `null` for null literals, mixed arrays, dynamic expressions, and non-string values.
+ *
+ * @param value The attribute value from `AST.Attribute['value']`.
+ * @returns The resolved static string, or `null` if the value is dynamic.
+ */
+export const extract_static_string = (value: AST.Attribute['value']): string | null => {
+	// Boolean attribute (e.g., <Mdz inline />)
+	if (value === true) return null;
+
+	// Plain attribute: content="text"
+	if (Array.isArray(value)) {
+		const first = value[0];
+		if (value.length === 1 && first?.type === 'Text') {
+			return first.data;
+		}
+		return null;
+	}
+
+	// ExpressionTag: content={expr}
+	const expr = value.expression;
+	// Null literal
+	if (expr.type === 'Literal' && expr.value === null) return null;
+	return evaluate_static_expr(expr);
+};
+
+/**
+ * Resolves local names that import from specified source paths.
+ *
+ * Scans `ImportDeclaration` nodes in both the instance and module scripts.
+ * Handles default, named, and aliased imports. Skips namespace imports.
+ * Returns import node references alongside names to support import removal.
+ *
+ * @param ast The parsed Svelte AST root node.
+ * @param component_imports Array of import source paths to match against.
+ * @returns Map of local names to their resolved import info.
+ */
+export const resolve_component_names = (
+	ast: AST.Root,
+	component_imports: Array<string>,
+): Map<string, ResolvedComponentImport> => {
+	const names: Map<string, ResolvedComponentImport> = new Map();
+	for (const script of [ast.instance, ast.module]) {
+		if (!script) continue;
+		for (const node of script.content.body) {
+			if (node.type !== 'ImportDeclaration') continue;
+			if (!component_imports.includes(node.source.value as string)) continue;
+			for (const specifier of node.specifiers) {
+				if (specifier.type === 'ImportNamespaceSpecifier') continue;
+				names.set(specifier.local.name, {import_node: node, specifier});
+			}
+		}
+	}
+	return names;
+};
+
+/**
+ * Finds the position to insert new import statements within a script block.
+ *
+ * Returns the end position of the last `ImportDeclaration`, or the start
+ * of the script body content if no imports exist.
+ *
+ * @param script The parsed `AST.Script` node.
+ * @returns The character position where new imports should be inserted.
+ */
+export const find_import_insert_position = (script: AST.Script): number => {
+	let last_import_end = -1;
+	for (const node of script.content.body) {
+		if (node.type === 'ImportDeclaration') {
+			// Svelte's parser always provides position data on AST nodes
+			last_import_end = (node as unknown as AST.BaseNode).end;
+		}
+	}
+	if (last_import_end !== -1) {
+		return last_import_end;
+	}
+	return (script.content as unknown as AST.BaseNode).start;
+};
+
+/**
+ * Generates indented import statement lines from an import map.
+ *
+ * Default imports produce `import Name from 'path';` lines.
+ * Named imports are grouped by path into `import {a, b} from 'path';` lines.
+ *
+ * @param imports Map of local names to their import info.
+ * @param indent Indentation prefix for each line. @default '\t'
+ * @returns A string of newline-separated import statements.
+ */
+export const generate_import_lines = (
+	imports: Map<string, PreprocessImportInfo>,
+	indent: string = '\t',
+): string => {
+	const default_imports: Array<[string, string]> = [];
+	const named_by_path: Map<string, Array<string>> = new Map();
+
+	for (const [name, {path, kind}] of imports) {
+		if (kind === 'default') {
+			default_imports.push([name, path]);
+		} else {
+			let names = named_by_path.get(path);
+			if (!names) {
+				names = [];
+				named_by_path.set(path, names);
+			}
+			names.push(name);
+		}
+	}
+
+	const lines: Array<string> = [];
+	for (const [name, path] of default_imports) {
+		lines.push(`${indent}import ${name} from '${path}';`);
+	}
+	for (const [path, names] of named_by_path) {
+		lines.push(`${indent}import {${names.join(', ')}} from '${path}';`);
+	}
+	return lines.join('\n');
+};
+
+/**
+ * Checks if an identifier with the given name appears anywhere in an AST subtree.
+ *
+ * Recursively walks all object and array properties of the tree, matching
+ * ESTree `Identifier` nodes (`{type: 'Identifier', name}`). Nodes in the
+ * `skip` set are excluded from traversal — used to skip `ImportDeclaration`
+ * nodes so the import's own specifier identifier doesn't false-positive.
+ *
+ * Safe for Svelte template ASTs: `Component.name` is a plain string property
+ * (not an `Identifier` node), so `<Mdz>` tags do not produce false matches.
+ *
+ * @param node The AST subtree to search.
+ * @param name The identifier name to look for.
+ * @param skip Set of AST nodes to skip during traversal.
+ * @returns `true` if a matching `Identifier` node is found.
+ */
+export const has_identifier_in_tree = (
+	node: unknown,
+	name: string,
+	skip?: Set<unknown>,
+): boolean => {
+	if (node === null || node === undefined || typeof node !== 'object') return false;
+	if (skip?.has(node)) return false;
+	if (Array.isArray(node)) {
+		return node.some((child) => has_identifier_in_tree(child, name, skip));
+	}
+	const record = node as Record<string, unknown>;
+	if (record.type === 'Identifier' && record.name === name) return true;
+	for (const key of Object.keys(record)) {
+		if (has_identifier_in_tree(record[key], name, skip)) return true;
+	}
+	return false;
+};
+
+/**
+ * Escapes text for safe embedding in Svelte template markup.
+ *
+ * Uses a single-pass regex replacement to avoid corruption that occurs with sequential
+ * `.replace()` calls (where the second replace matches characters introduced by the first).
+ *
+ * Escapes four characters:
+ * - `{` → `{'{'}` and `}` → `{'}'}` — prevents Svelte expression interpretation
+ * - `<` → `&lt;` — prevents HTML/Svelte tag interpretation
+ * - `&` → `&amp;` — prevents HTML entity interpretation
+ *
+ * The `&` escaping is necessary because runtime `MdzNodeView.svelte` renders text
+ * with `{node.content}` (a Svelte expression), which auto-escapes `&` to `&amp;`.
+ * The preprocessor emits raw template text where `&` is NOT auto-escaped, so
+ * manual escaping is required to match the runtime behavior.
+ */
+export const escape_svelte_text = (text: string): string =>
+	text.replace(/[{}<&]/g, (ch) => {
+		switch (ch) {
+			case '{':
+				return "{'{'}";
+			case '}':
+				return "{'}'}";
+			case '<':
+				return '&lt;';
+			case '&':
+				return '&amp;';
+			default:
+				return ch;
+		}
+	});