@fuzdev/fuz_util 0.48.3 → 0.49.0

package/dist/sort.js

@@ -0,0 +1,123 @@
+/**
+ * Generic topological sort using Kahn's algorithm.
+ *
+ * Orders items so that dependencies come before dependents.
+ * Works with any item type that has `id` and optional `depends_on`.
+ *
+ * @module
+ */
+/**
+ * Sort items by their dependencies using Kahn's algorithm.
+ *
+ * Returns items ordered so that dependencies come before dependents.
+ * If a cycle is detected, returns an error with the cycle path.
+ *
+ * @param items - Array of items to sort.
+ * @param label - Label for error messages (e.g. "resource", "step").
+ * @returns Sorted items or error if cycle detected.
+ */
+export const topological_sort = (items, label = 'item') => {
+    // Build id -> item map
+    const item_map = new Map();
+    for (const item of items) {
+        if (item_map.has(item.id)) {
+            return { ok: false, error: `duplicate ${label} id: ${item.id}` };
+        }
+        item_map.set(item.id, item);
+    }
+    // Validate all dependencies exist and count dependents per item
+    // dependents_count[X] = how many items list X in their depends_on
+    const dependents_count = new Map();
+    for (const item of items) {
+        dependents_count.set(item.id, 0);
+    }
+    for (const item of items) {
+        const deps = item.depends_on ?? [];
+        for (const dep of deps) {
+            if (!item_map.has(dep)) {
+                return { ok: false, error: `${label} "${item.id}" depends on unknown ${label} "${dep}"` };
+            }
+            dependents_count.set(dep, dependents_count.get(dep) + 1);
+        }
+    }
+    // Start from leaf items (nothing depends on them), work toward roots
+    const queue = [];
+    for (const [id, count] of dependents_count) {
+        if (count === 0) {
+            queue.push(id);
+        }
+    }
+    // Process leaves first, then items whose dependents are all processed
+    const sorted = [];
+    const visited = new Set();
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (visited.has(id))
+            continue;
+        visited.add(id);
+        sorted.push(item_map.get(id));
+        // This item is processed — decrement its dependencies' dependent counts
+        const deps = item_map.get(id).depends_on ?? [];
+        for (const dep of deps) {
+            const new_count = dependents_count.get(dep) - 1;
+            dependents_count.set(dep, new_count);
+            if (new_count === 0) {
+                queue.push(dep);
+            }
+        }
+    }
+    // Check for cycle
+    if (sorted.length !== items.length) {
+        const unvisited = items.filter((item) => !visited.has(item.id)).map((item) => item.id);
+        const cycle = find_cycle(item_map, unvisited);
+        return {
+            ok: false,
+            error: `dependency cycle detected: ${cycle.join(' -> ')}`,
+            cycle,
+        };
+    }
+    // Reverse: leaves were processed first, but dependencies must come first in output
+    sorted.reverse();
+    return { ok: true, sorted };
+};
+/**
+ * Find a cycle in the dependency graph starting from unvisited nodes.
+ * Used for error reporting when a cycle is detected.
+ */
+const find_cycle = (item_map, unvisited) => {
+    const unvisited_set = new Set(unvisited);
+    // DFS to find cycle
+    const path = [];
+    const in_path = new Set();
+    const dfs = (id) => {
+        if (in_path.has(id)) {
+            path.push(id);
+            return true;
+        }
+        if (!unvisited_set.has(id))
+            return false;
+        in_path.add(id);
+        path.push(id);
+        const item = item_map.get(id);
+        const deps = item?.depends_on ?? [];
+        for (const dep of deps) {
+            if (dfs(dep))
+                return true;
+        }
+        in_path.delete(id);
+        path.pop();
+        return false;
+    };
+    if (unvisited.length > 0) {
+        dfs(unvisited[0]);
+    }
+    // Extract just the cycle portion
+    if (path.length > 0) {
+        const last = path[path.length - 1];
+        const cycle_start = path.indexOf(last);
+        if (cycle_start < path.length - 1) {
+            return path.slice(cycle_start);
+        }
+    }
+    return unvisited;
+};

package/dist/source_json.d.ts

@@ -16,10 +16,10 @@ import { z } from 'zod';
 export declare const DeclarationKind: z.ZodEnum<{
     function: "function";
     type: "type";
-    constructor: "constructor";
     json: "json";
     variable: "variable";
     class: "class";
+    constructor: "constructor";
     component: "component";
     css: "css";
 }>;
@@ -80,10 +80,10 @@ export declare const DeclarationJson: z.ZodObject<{
     kind: z.ZodEnum<{
         function: "function";
         type: "type";
-        constructor: "constructor";
         json: "json";
         variable: "variable";
         class: "class";
+        constructor: "constructor";
         component: "component";
         css: "css";
     }>;
@@ -172,10 +172,10 @@ export declare const ModuleJson: z.ZodObject<{
         kind: z.ZodEnum<{
             function: "function";
             type: "type";
-            constructor: "constructor";
             json: "json";
             variable: "variable";
             class: "class";
+            constructor: "constructor";
             component: "component";
             css: "css";
         }>;
@@ -279,10 +279,10 @@ export declare const SourceJson: z.ZodObject<{
             kind: z.ZodEnum<{
                 function: "function";
                 type: "type";
-                constructor: "constructor";
                 json: "json";
                 variable: "variable";
                 class: "class";
+                constructor: "constructor";
                 component: "component";
                 css: "css";
             }>;

package/dist/string.d.ts

@@ -70,4 +70,20 @@ 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.
+ *
+ * Checks for null bytes in the first 8KB of content.
+ *
+ * @param content - Content to check.
+ * @returns True if content appears to be binary.
+ */
+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"}
+{"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,3 +191,36 @@ 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.
+ *
+ * Checks for null bytes in the first 8KB of content.
+ *
+ * @param content - Content to check.
+ * @returns True if content appears to be binary.
+ */
+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.3",
+  "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
     }
@@ -62,14 +70,15 @@
   "devDependencies": {
     "@changesets/changelog-git": "^0.2.1",
     "@fuzdev/fuz_code": "^0.41.0",
-    "@fuzdev/fuz_css": "^0.45.0",
-    "@fuzdev/fuz_ui": "^0.180.0",
+    "@fuzdev/fuz_css": "^0.47.0",
+    "@fuzdev/fuz_ui": "^0.181.1",
     "@ryanatkn/eslint-config": "^0.9.0",
-    "@ryanatkn/gro": "^0.189.3",
+    "@ryanatkn/gro": "^0.190.0",
     "@sveltejs/adapter-static": "^3.0.10",
     "@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",
@@ -79,8 +88,8 @@
     "fast-deep-equal": "^3.1.3",
     "prettier": "^3.7.4",
     "prettier-plugin-svelte": "^3.4.1",
-    "svelte": "^5.48.5",
-    "svelte-check": "^4.3.5",
+    "svelte": "^5.49.1",
+    "svelte-check": "^4.3.6",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.48.1",