@woosh/meep-engine 3.1.0 → 3.2.0

package/src/shade/renderer/loader/usd/parse_usda.js

@@ -1,931 +1,931 @@
-/**
- * USDA (USD ASCII) text parser.
- *
- * Parses `.usda` files into a flat `specsByPath` intermediate representation
- * that is shared with the USDC binary parser. This ensures a single scene
- * builder can consume output from either format.
- *
- * @see https://openusd.org/release/glossary.html#usdglossary-usda — USDA format description
- * @see https://openusd.org/release/tut_inspect_and_author_props.html — Attribute authoring
- * @see https://openusd.org/release/api/sdf_page_front.html — Sdf layer file format
- *
- * Supports:
- * - Stage metadata (`#usda 1.0 ( ... )`)
- * - `def`, `over`, `class` prim specifiers
- * - Typed attributes: float, double, int, bool, string, token, asset, color3f,
- *   point3f, normal3f, texCoord2f, and their array variants
- * - Relationships: `rel material:binding = </path>`
- * - Transform ops: `xformOp:*` and `xformOpOrder`
- * - Primvars: `primvars:st`, `primvars:st:indices`, etc.
- * - TimeSamples: `float3[].timeSamples = { 0: (...), ... }`
- * - Block comments `/* ... *‍/`, line comments `# ...`
- * - Multi-line array values `[...\n...\n...]`
- *
- * Not supported (logged as warnings):
- * - Composition arcs: `references`, `payloads`, `sublayers`, `inherits`
- * - Variant sets and variant selections
- *
- * @module parse_usda
- */
-
-import { UsdParseError } from "./UsdError.js";
-
-
-/**
- * Spec type constants matching SdfSpecType values from the USD schema.
- * @see https://openusd.org/release/api/class_sdf_spec_type.html
- * @enum {number}
- */
-const SpecType = {
-    Attribute: 1,
-    Prim: 6,
-    Relationship: 8,
-};
-
-/**
- * Pre-compiled regex for matching prim definition lines.
- * @see https://openusd.org/release/glossary.html#usdglossary-specifier — def/over/class specifiers
- * Captures: [1] = specifier (def|over|class), [2] = type name (optional), [3] = prim name
- * @type {RegExp}
- */
-const DEF_MATCH = /^(def|over|class)\s+(?:(\w+)\s+)?"([^"]+)"$/;
-
-/**
- * Pre-compiled regex for matching typed attribute declarations.
- * Captures: [1] = qualifier (optional), [2] = type, [3] = attribute name
- * @type {RegExp}
- */
-const ATTR_MATCH = /^(?:(uniform|custom)\s+)?(\w+(?:\[\])?)\s+(.+)$/;
-
-/**
- * Tree-key suffix under which an attribute's parenthesized metadata block
- * (e.g. `interpolation = "faceVarying"`) is stored alongside its value.
- * Contains characters illegal in USDA property names, so it cannot collide.
- * @type {string}
- */
-const META_KEY_SUFFIX = " (meta)";
-
-/**
- * Matches one `name = value` metadata entry. Values keep their raw text
- * (quotes intact) to mirror parse_tree's metadata-block representation.
- * @type {RegExp}
- */
-const META_ENTRY_MATCH = /([A-Za-z_][\w:]*)\s*=\s*("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|[^\s;()]+)/g;
-
-
-/**
- * Parse a USDA text file into the unified `specsByPath` format.
- *
- * @param {string} text - Raw USDA file content
- * @returns {{ specsByPath: Object.<string, { specType: number, fields: Object }> }}
- * @throws {UsdParseError} On malformed USDA syntax
- */
-export function parse_usda(text) {
-
-    // Step 1: Preprocess the raw text
-    const processed = preprocess(text);
-
-    // Step 2: Parse into a raw nested object tree
-    const tree = parse_tree(processed);
-
-    // Step 3: Walk the tree and emit specsByPath entries
-    const specs_by_path = {};
-
-    // Parse root/stage metadata
-    const root_fields = extract_stage_metadata(tree);
-    specs_by_path["/"] = { specType: SpecType.Prim, fields: root_fields };
-
-    // Walk all prim definitions
-    walk_tree(tree, "/", specs_by_path);
-
-    return { specsByPath: specs_by_path };
-}
-
-
-// ============================================================================
-// Preprocessing
-// ============================================================================
-
-/**
- * Preprocess USDA text: strip comments, collapse multi-line values,
- * normalize whitespace.
- *
- * @param {string} text
- * @returns {string}
- */
-function preprocess(text) {
-
-    // Remove block comments /* ... */
-    text = strip_block_comments(text);
-
-    // Collapse triple-quoted strings to single lines
-    text = collapse_triple_quotes(text);
-
-    const lines = text.split("\n");
-    const result = [];
-
-    let in_multiline = false;
-    let bracket_depth = 0;
-    let accumulated = "";
-
-    for (let i = 0; i < lines.length; i++) {
-        let line = lines[i];
-
-        // Strip inline comments (preserving #usda header)
-        line = strip_inline_comment(line);
-
-        const trimmed = line.trim();
-
-        if (in_multiline) {
-            accumulated += " " + trimmed;
-
-            for (let c = 0; c < trimmed.length; c++) {
-                if (trimmed[c] === "[") bracket_depth++;
-                else if (trimmed[c] === "]") bracket_depth--;
-            }
-
-            if (bracket_depth === 0) {
-                result.push(accumulated);
-                accumulated = "";
-                in_multiline = false;
-            }
-
-        } else {
-
-            // Detect start of a multi-line array value
-            if (trimmed.includes("=")) {
-                const eq_index = find_assignment_operator(trimmed);
-
-                if (eq_index !== -1) {
-                    const rhs = trimmed.slice(eq_index + 1).trim();
-
-                    let open = 0;
-                    let close = 0;
-
-                    for (let c = 0; c < rhs.length; c++) {
-                        if (rhs[c] === "[") open++;
-                        else if (rhs[c] === "]") close++;
-                    }
-
-                    if (open > close) {
-                        in_multiline = true;
-                        bracket_depth = open - close;
-                        accumulated = trimmed;
-                        continue;
-                    }
-                }
-            }
-
-            result.push(trimmed);
-        }
-    }
-
-    return result.join("\n");
-}
-
-
-/**
- * @param {string} text
- * @returns {string}
- */
-function strip_block_comments(text) {
-    // Use regex for O(N) performance instead of char-by-char string concatenation
-    return text.replace(/\/\*[\s\S]*?\*\//g, "");
-}
-
-
-/**
- * Collapse triple-quoted strings (''' or \"\"\") onto single lines.
- * @param {string} text
- * @returns {string}
- */
-function collapse_triple_quotes(text) {
-    const parts = [];
-    let i = 0;
-    let segment_start = 0;
-
-    while (i < text.length) {
-        if (i + 2 < text.length) {
-            const triple = text.slice(i, i + 3);
-
-            if (triple === "'''" || triple === '"""') {
-                // Flush text before this triple-quote
-                parts.push(text.slice(segment_start, i));
-                parts.push(triple);
-                i += 3;
-
-                const inner = [];
-
-                while (i < text.length) {
-                    if (i + 2 < text.length && text.slice(i, i + 3) === triple) {
-                        parts.push(inner.join(""));
-                        parts.push(triple);
-                        i += 3;
-                        break;
-                    } else if (text[i] === "\n") {
-                        inner.push("\\n");
-                    } else if (text[i] !== "\r") {
-                        inner.push(text[i]);
-                    }
-
-                    i++;
-                }
-
-                segment_start = i;
-                continue;
-            }
-        }
-
-        i++;
-    }
-
-    // Flush remaining text
-    parts.push(text.slice(segment_start));
-
-    return parts.join("");
-}
-
-
-/**
- * Strip an inline `#` comment, respecting string boundaries.
- * Preserves `#usda` header lines.
- * @param {string} line
- * @returns {string}
- */
-function strip_inline_comment(line) {
-
-    if (line.trim().startsWith("#usda")) {
-        return line;
-    }
-
-    let in_string = false;
-    let string_char = null;
-    let escaped = false;
-
-    for (let i = 0; i < line.length; i++) {
-        const ch = line[i];
-
-        if (escaped) {
-            escaped = false;
-            continue;
-        }
-
-        if (ch === "\\") {
-            escaped = true;
-            continue;
-        }
-
-        if (!in_string && (ch === '"' || ch === "'")) {
-            in_string = true;
-            string_char = ch;
-        } else if (in_string && ch === string_char) {
-            in_string = false;
-            string_char = null;
-        } else if (!in_string && ch === "#") {
-            return line.slice(0, i).trimEnd();
-        }
-    }
-
-    return line;
-}
-
-
-/**
- * Find the first `=` not inside a quoted string.
- * @param {string} line
- * @returns {number} Index of `=`, or -1
- */
-function find_assignment_operator(line) {
-    let in_string = false;
-    let string_char = null;
-    let escaped = false;
-
-    for (let i = 0; i < line.length; i++) {
-        const ch = line[i];
-
-        if (escaped) {
-            escaped = false;
-            continue;
-        }
-
-        if (ch === "\\") {
-            escaped = true;
-            continue;
-        }
-
-        if (!in_string && (ch === '"' || ch === "'")) {
-            in_string = true;
-            string_char = ch;
-        } else if (in_string && ch === string_char) {
-            in_string = false;
-        } else if (!in_string && ch === "=") {
-            return i;
-        }
-    }
-
-    return -1;
-}
-
-
-// ============================================================================
-// Tree Parsing
-// ============================================================================
-
-/**
- * Parse preprocessed USDA lines into a nested object tree.
- *
- * Each `def TypeName "name" { ... }` block becomes a keyed sub-object.
- * Properties become key-value pairs within their owning object.
- *
- * @param {string} text - Preprocessed USDA text
- * @returns {Object}
- */
-function parse_tree(text) {
-
-    const root = {};
-    const lines = text.split("\n");
-
-    let pending_key = null;
-    let target = root;
-    const stack = [root];
-
-    for (const raw_line of lines) {
-        const line = raw_line.trim();
-
-        if (line.length === 0) {
-            continue;
-        }
-
-        if (line.includes("=")) {
-            const eq_index = find_assignment_operator(line);
-
-            if (eq_index === -1) {
-                pending_key = line;
-                continue;
-            }
-
-            const lhs = line.slice(0, eq_index).trim();
-            const rhs = line.slice(eq_index + 1).trim();
-
-            if (rhs.endsWith("{")) {
-                const group = {};
-                stack.push(group);
-                target[lhs] = group;
-                target = group;
-            } else if (rhs.endsWith("(")) {
-                // Metadata annotation block — the value stays on the key,
-                // the block's entries are stored alongside under META_KEY_SUFFIX
-                target[lhs] = rhs.slice(0, -1).trim();
-                const meta = {};
-                target[lhs + META_KEY_SUFFIX] = meta;
-                stack.push(meta);
-                target = meta;
-            } else {
-                target[lhs] = rhs;
-            }
-
-        } else if (line.includes(":") && !line.includes("=")) {
-            // Dictionary entries like "0: [(...)...]" for timeSamples
-            const colon_index = line.indexOf(":");
-            const key = line.slice(0, colon_index).trim();
-            const value = line.slice(colon_index + 1).trim();
-
-            if (/^[\d.]+$/.test(key)) {
-                target[key] = value;
-            }
-
-        } else if (line.endsWith("{")) {
-            const group = target[pending_key] || {};
-            stack.push(group);
-            target[pending_key] = group;
-            target = group;
-
-        } else if (line.endsWith("}")) {
-            stack.pop();
-
-            if (stack.length === 0) continue;
-
-            target = stack[stack.length - 1];
-
-        } else if (line.endsWith("(")) {
-            const meta = {};
-            stack.push(meta);
-            pending_key = line.split("(")[0].trim() || pending_key;
-            target[pending_key] = meta;
-            target = meta;
-
-        } else if (line.endsWith(")")) {
-            stack.pop();
-            target = stack[stack.length - 1];
-
-        } else {
-            pending_key = line;
-        }
-    }
-
-    return root;
-}
-
-
-// ============================================================================
-// Stage Metadata Extraction
-// ============================================================================
-
-/**
- * Extract stage metadata from the `#usda 1.0` header block.
- *
- * @see https://openusd.org/release/api/class_usd_stage.html — Stage-level metadata
- * @see https://openusd.org/release/api/class_usd_geom_set_stage_up_axis.html — upAxis
- * @see https://openusd.org/release/api/class_usd_geom_linear_units.html — metersPerUnit
- *
- * @param {Object} tree - Parsed tree
- * @returns {Object} Root prim fields with `upAxis`, `defaultPrim`, `metersPerUnit`
- */
-function extract_stage_metadata(tree) {
-
-    const fields = {};
-    const header = tree["#usda 1.0"];
-
-    if (!header) {
-        return fields;
-    }
-
-    if (header.upAxis) {
-        fields.upAxis = strip_quotes(header.upAxis);
-    }
-
-    if (header.defaultPrim) {
-        fields.defaultPrim = strip_quotes(header.defaultPrim);
-    }
-
-    if (header.metersPerUnit !== undefined) {
-        fields.metersPerUnit = parseFloat(header.metersPerUnit);
-    }
-
-    if (header.doc) {
-        fields.doc = strip_quotes(header.doc);
-    }
-
-    return fields;
-}
-
-
-// ============================================================================
-// Tree Walking → specsByPath
-// ============================================================================
-
-/**
- * Recursively walk the parsed tree and emit specsByPath entries.
- *
- * @param {Object} data - Current tree node
- * @param {string} parent_path - Parent prim path
- * @param {Object} specs_by_path - Output map (modified in place)
- */
-function walk_tree(data, parent_path, specs_by_path) {
-
-    const prim_children = [];
-
-    for (const key in data) {
-        if (key === "#usda 1.0") continue;
-        if (key === "variants") continue;
-
-        const def_match = key.match(DEF_MATCH);
-
-        if (!def_match) continue;
-
-        const specifier = def_match[1]; // "def", "over", or "class"
-        const type_name = def_match[2] || "";
-        const name = def_match[3];
-        const path = parent_path === "/" ? "/" + name : parent_path + "/" + name;
-
-        prim_children.push(name);
-
-        const prim_fields = { typeName: type_name, specifier };
-        const prim_data = data[key];
-
-        // Extract attributes, relationships, and xformOps
-        extract_prim_data(prim_data, path, prim_fields, specs_by_path);
-
-        specs_by_path[path] = { specType: SpecType.Prim, fields: prim_fields };
-
-        // Recurse into children
-        walk_tree(prim_data, path, specs_by_path);
-    }
-
-    // Attach primChildren to parent spec
-    if (prim_children.length > 0 && specs_by_path[parent_path]) {
-        specs_by_path[parent_path].fields.primChildren = prim_children;
-    }
-}
-
-
-/**
- * Extract attributes, relationships, and xformOps from a prim's tree data.
- *
- * @param {Object} data - Prim tree object
- * @param {string} path - Prim path
- * @param {Object} prim_fields - Prim fields to populate
- * @param {Object} specs_by_path - Output map
- */
-function extract_prim_data(data, path, prim_fields, specs_by_path) {
-
-    if (!data || typeof data !== "object") return;
-
-    for (const key in data) {
-
-        // Skip nested def blocks (handled by walk_tree)
-        if (key.startsWith("def ") || key.startsWith("over ") || key.startsWith("class ")) continue;
-
-        // Metadata sibling entries are consumed alongside their attribute below
-        if (key.endsWith(META_KEY_SUFFIX)) continue;
-
-        // Composition arcs — warn and skip
-        if (key === "prepend references" || key === "references") {
-            console.warn(`[USD] Composition arc "references" at ${path} is not supported, skipping`);
-            continue;
-        }
-
-        if (key === "payload") {
-            console.warn(`[USD] Composition arc "payload" at ${path} is not supported, skipping`);
-            continue;
-        }
-
-        // Relationships
-        // @see https://openusd.org/release/glossary.html#usdglossary-relationship
-        if (key.startsWith("rel ")) {
-            const rel_name = key.slice(4);
-            const rel_path = path + "." + rel_name;
-            const target = String(data[key]).replace(/[<>]/g, "");
-
-            specs_by_path[rel_path] = {
-                specType: SpecType.Relationship,
-                fields: { targetPaths: [target] }
-            };
-            continue;
-        }
-
-        // xformOpOrder
-        // @see https://openusd.org/release/api/class_usd_geom_xformable.html#details
-        if (key.includes("xformOpOrder")) {
-            prim_fields.xformOpOrder = parse_string_array(data[key]);
-            continue;
-        }
-
-        // Typed attributes
-        const attr_match = key.match(ATTR_MATCH);
-        if (!attr_match) continue;
-
-        const value_type = attr_match[2];
-        const attr_name = attr_match[3];
-        const raw_value = data[key];
-
-        // Connection attributes (e.g. "inputs:diffuseColor.connect = </path>")
-        if (attr_name.endsWith(".connect")) {
-            const base_name = attr_name.slice(0, -8);
-            const attr_path = path + "." + base_name;
-
-            let conn_path = String(raw_value).trim();
-            if (conn_path.startsWith("<")) conn_path = conn_path.slice(1);
-            if (conn_path.endsWith(">")) conn_path = conn_path.slice(0, -1);
-
-            const spec = obtain_attribute_spec(specs_by_path, attr_path, value_type);
-            spec.fields.connectionPaths = [conn_path];
-            continue;
-        }
-
-        // TimeSamples
-        if (attr_name.endsWith(".timeSamples") && typeof raw_value === "object") {
-            const base_name = attr_name.slice(0, -12);
-            const attr_path = path + "." + base_name;
-
-            const times = [];
-            const values = [];
-
-            for (const frame_key in raw_value) {
-                const frame = parseFloat(frame_key);
-                if (isNaN(frame)) continue;
-
-                times.push(frame);
-                values.push(parse_attribute_value(value_type, raw_value[frame_key]));
-            }
-
-            // Sort by time
-            const sorted = times
-                .map((t, i) => ({ t, v: values[i] }))
-                .sort((a, b) => a.t - b.t);
-
-            const spec = obtain_attribute_spec(specs_by_path, attr_path, value_type);
-            spec.fields.timeSamples = {
-                times: sorted.map(s => s.t),
-                values: sorted.map(s => s.v)
-            };
-            continue;
-        }
-
-        // Regular attribute
-        let value_text = raw_value;
-
-        // Block-form metadata (`= value (\n ... \n)`) is stored by parse_tree
-        // under the META_KEY_SUFFIX sibling key
-        let meta = data[key + META_KEY_SUFFIX];
-
-        // Single-line form: `= value ( interpolation = "faceVarying" )` — the
-        // metadata rides inside the value text and must be split off before
-        // value parsing
-        if (typeof raw_value === "string") {
-            const split = split_inline_metadata(raw_value);
-
-            value_text = split.value;
-
-            if (split.meta !== null) {
-                meta = split.meta;
-            }
-        }
-
-        const parsed_value = parse_attribute_value(value_type, value_text);
-        const attr_path = path + "." + attr_name;
-
-        const spec = obtain_attribute_spec(specs_by_path, attr_path, value_type);
-        spec.fields.default = parsed_value;
-
-        if (meta !== undefined) {
-            spec.fields.metadata = meta;
-
-            // @see https://openusd.org/release/glossary.html#usdglossary-interpolation
-            if (meta.interpolation !== undefined) {
-                spec.fields.interpolation = strip_quotes(String(meta.interpolation));
-            }
-        }
-    }
-}
-
-
-/**
- * Get or create an attribute spec, merging field updates into an existing
- * entry. USDA authors one field per line (`.connect`, `.timeSamples`, the
- * default value) — a later line must not clobber fields set by earlier ones.
- *
- * @param {Object} specs_by_path
- * @param {string} attr_path
- * @param {string} value_type
- * @returns {{ specType: number, fields: Object }}
- */
-function obtain_attribute_spec(specs_by_path, attr_path, value_type) {
-
-    let spec = specs_by_path[attr_path];
-
-    if (spec === undefined) {
-        spec = {
-            specType: SpecType.Attribute,
-            fields: { typeName: value_type }
-        };
-
-        specs_by_path[attr_path] = spec;
-    } else if (spec.fields.typeName === undefined) {
-        spec.fields.typeName = value_type;
-    }
-
-    return spec;
-}
-
-
-// ============================================================================
-// Value Parsing
-// ============================================================================
-
-/**
- * Parse a raw USDA attribute value string into a typed JS value.
- *
- * @param {string} value_type - USD type name (e.g. "float3[]", "token", "asset")
- * @param {*} raw - Raw string or already-parsed value
- * @returns {*} Parsed value (number, array, string, etc.)
- */
-function parse_attribute_value(value_type, raw) {
-
-    if (raw === undefined || raw === null) return undefined;
-
-    const str = String(raw).trim();
-
-    // Array types
-    if (value_type.endsWith("[]")) {
-        return parse_array_value(value_type, str);
-    }
-
-    // Quaternion types — stored in USD's native (w, x, y, z) order.
-    // Conversion to the engine's (x, y, z, w) is done in usd_compose_transform
-    // when the quaternion is consumed for matrix composition.
-    // @see https://openusd.org/release/api/class_gf_quatf.html — GfQuatf real-part-first layout
-    if (value_type.startsWith("quat")) {
-        const cleaned = str.replace(/[()]/g, "");
-        return cleaned.split(",").map(s => parseFloat(s.trim()));
-    }
-
-    // Vector types (float2, float3, float4, double3, point3f, color3f, normal3f, etc.)
-    if (/\d/.test(value_type) && (
-        value_type.includes("float") || value_type.includes("double") ||
-        value_type.includes("int") || value_type.startsWith("point") ||
-        value_type.startsWith("color") || value_type.startsWith("normal") ||
-        value_type.startsWith("texCoord") || value_type.startsWith("vec")
-    )) {
-        const cleaned = str.replace(/[()]/g, "");
-        return cleaned.split(",").map(s => parseFloat(s.trim()));
-    }
-
-    // Matrix types
-    if (value_type.includes("matrix")) {
-        const cleaned = str.replace(/[()]/g, "");
-        return cleaned.split(",").map(s => parseFloat(s.trim()));
-    }
-
-    // Scalar numeric types
-    if (value_type === "float" || value_type === "double" || value_type === "half") {
-        return parseFloat(str);
-    }
-
-    if (value_type === "int") {
-        return parseInt(str, 10);
-    }
-
-    if (value_type === "bool") {
-        return str === "true" || str === "1";
-    }
-
-    // Asset path
-    if (value_type === "asset") {
-        return str.replace(/@/g, "").replace(/"/g, "");
-    }
-
-    // String / token
-    if (value_type === "string" || value_type === "token") {
-        return strip_quotes(str);
-    }
-
-    // Fallback
-    return strip_quotes(str);
-}
-
-
-/**
- * Parse a USDA array value string.
- *
- * Handles `[(1, 2, 3), (4, 5, 6)]` → flat `[1, 2, 3, 4, 5, 6]`
- * and simple `[1, 2, 3]` → `[1, 2, 3]`
- *
- * @param {string} value_type - USD array type (e.g. "float3[]")
- * @param {string} str - Raw value string
- * @returns {number[]|string[]}
- */
-function parse_array_value(value_type, str) {
-
-    try {
-        // Replace USDA tuple parens with JSON brackets, strip trailing comma
-        let cleaned = str.replace(/\(/g, "[").replace(/\)/g, "]");
-
-        if (cleaned.endsWith(",")) {
-            cleaned = cleaned.slice(0, -1);
-        }
-
-        const parsed = JSON.parse(cleaned);
-
-        // Flatten nested arrays for vector types: [[1,2,3],[4,5,6]] → [1,2,3,4,5,6]
-        if (Array.isArray(parsed) && parsed.length > 0 && Array.isArray(parsed[0])) {
-            return parsed.flat();
-        }
-
-        return parsed;
-    } catch (_) {
-        // Fallback: simple split parsing
-        const cleaned = str.replace(/[\[\]]/g, "");
-
-        return cleaned.split(",").map(s => {
-            const trimmed = s.trim();
-            const num = parseFloat(trimmed);
-            return isNaN(num) ? strip_quotes(trimmed) : num;
-        });
-    }
-}
-
-
-/**
- * Split a single-line attribute value of the form `value ( meta )` into the
- * value text and parsed metadata entries.
- *
- * The metadata block is a top-level parenthesized group that FOLLOWS the
- * value — for tuple values the leading `(...)` group is the value itself,
- * so only a `(` seen at depth 0 after a complete value token starts metadata.
- *
- * @param {string} str - Trimmed raw value text
- * @returns {{ value: string, meta: Object.<string, string>|null }}
- */
-function split_inline_metadata(str) {
-
-    let depth = 0;
-    let in_string = false;
-    let string_char = null;
-    let escaped = false;
-    let seen_value = false;
-
-    for (let i = 0; i < str.length; i++) {
-        const ch = str[i];
-
-        if (escaped) {
-            escaped = false;
-            continue;
-        }
-
-        if (ch === "\\") {
-            escaped = true;
-            continue;
-        }
-
-        if (in_string) {
-            if (ch === string_char) {
-                in_string = false;
-            }
-            continue;
-        }
-
-        if (ch === '"' || ch === "'") {
-            in_string = true;
-            string_char = ch;
-            seen_value = true;
-        } else if (ch === "(") {
-            if (depth === 0 && seen_value) {
-                // Metadata block start — everything before it is the value
-                const meta_text = str.slice(i + 1, str.lastIndexOf(")"));
-
-                return {
-                    value: str.slice(0, i).trim(),
-                    meta: parse_metadata_entries(meta_text)
-                };
-            }
-
-            depth++;
-            seen_value = true;
-        } else if (ch === "[") {
-            depth++;
-            seen_value = true;
-        } else if (ch === ")" || ch === "]") {
-            depth--;
-        } else if (!/\s/.test(ch)) {
-            seen_value = true;
-        }
-    }
-
-    return { value: str, meta: null };
-}
-
-
-/**
- * Parse metadata block entries (`name = value`, separated by newlines or
- * semicolons) into an object. Values keep their raw text (quotes intact)
- * to mirror parse_tree's metadata-block representation.
- *
- * @param {string} text
- * @returns {Object.<string, string>}
- */
-function parse_metadata_entries(text) {
-
-    const meta = {};
-
-    META_ENTRY_MATCH.lastIndex = 0;
-
-    let m;
-    while ((m = META_ENTRY_MATCH.exec(text)) !== null) {
-        meta[m[1]] = m[2];
-    }
-
-    return meta;
-}
-
-
-/**
- * Parse a string array value like `["xformOp:translate", "xformOp:scale"]`.
- *
- * @param {string} raw
- * @returns {string[]}
- */
-function parse_string_array(raw) {
-    const str = String(raw);
-
-    return str
-        .replace(/[\[\]]/g, "")
-        .split(",")
-        .map(s => s.trim().replace(/"/g, ""))
-        .filter(s => s.length > 0);
-}
-
-
-/**
- * Remove surrounding quotes from a string value.
- * @param {string} str
- * @returns {string}
- */
-function strip_quotes(str) {
-    if ((str.startsWith('"') && str.endsWith('"')) ||
-        (str.startsWith("'") && str.endsWith("'"))) {
-        return str.slice(1, -1);
-    }
-
-    return str;
-}
+/**
+ * USDA (USD ASCII) text parser.
+ *
+ * Parses `.usda` files into a flat `specsByPath` intermediate representation
+ * that is shared with the USDC binary parser. This ensures a single scene
+ * builder can consume output from either format.
+ *
+ * @see https://openusd.org/release/glossary.html#usdglossary-usda — USDA format description
+ * @see https://openusd.org/release/tut_inspect_and_author_props.html — Attribute authoring
+ * @see https://openusd.org/release/api/sdf_page_front.html — Sdf layer file format
+ *
+ * Supports:
+ * - Stage metadata (`#usda 1.0 ( ... )`)
+ * - `def`, `over`, `class` prim specifiers
+ * - Typed attributes: float, double, int, bool, string, token, asset, color3f,
+ *   point3f, normal3f, texCoord2f, and their array variants
+ * - Relationships: `rel material:binding = </path>`
+ * - Transform ops: `xformOp:*` and `xformOpOrder`
+ * - Primvars: `primvars:st`, `primvars:st:indices`, etc.
+ * - TimeSamples: `float3[].timeSamples = { 0: (...), ... }`
+ * - Block comments `/* ... *‍/`, line comments `# ...`
+ * - Multi-line array values `[...\n...\n...]`
+ *
+ * Not supported (logged as warnings):
+ * - Composition arcs: `references`, `payloads`, `sublayers`, `inherits`
+ * - Variant sets and variant selections
+ *
+ * @module parse_usda
+ */
+
+import { UsdParseError } from "./UsdError.js";
+
+
+/**
+ * Spec type constants matching SdfSpecType values from the USD schema.
+ * @see https://openusd.org/release/api/class_sdf_spec_type.html
+ * @enum {number}
+ */
+const SpecType = {
+    Attribute: 1,
+    Prim: 6,
+    Relationship: 8,
+};
+
+/**
+ * Pre-compiled regex for matching prim definition lines.
+ * @see https://openusd.org/release/glossary.html#usdglossary-specifier — def/over/class specifiers
+ * Captures: [1] = specifier (def|over|class), [2] = type name (optional), [3] = prim name
+ * @type {RegExp}
+ */
+const DEF_MATCH = /^(def|over|class)\s+(?:(\w+)\s+)?"([^"]+)"$/;
+
+/**
+ * Pre-compiled regex for matching typed attribute declarations.
+ * Captures: [1] = qualifier (optional), [2] = type, [3] = attribute name
+ * @type {RegExp}
+ */
+const ATTR_MATCH = /^(?:(uniform|custom)\s+)?(\w+(?:\[\])?)\s+(.+)$/;
+
+/**
+ * Tree-key suffix under which an attribute's parenthesized metadata block
+ * (e.g. `interpolation = "faceVarying"`) is stored alongside its value.
+ * Contains characters illegal in USDA property names, so it cannot collide.
+ * @type {string}
+ */
+const META_KEY_SUFFIX = " (meta)";
+
+/**
+ * Matches one `name = value` metadata entry. Values keep their raw text
+ * (quotes intact) to mirror parse_tree's metadata-block representation.
+ * @type {RegExp}
+ */
+const META_ENTRY_MATCH = /([A-Za-z_][\w:]*)\s*=\s*("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|[^\s;()]+)/g;
+
+
+/**
+ * Parse a USDA text file into the unified `specsByPath` format.
+ *
+ * @param {string} text - Raw USDA file content
+ * @returns {{ specsByPath: Object.<string, { specType: number, fields: Object }> }}
+ * @throws {UsdParseError} On malformed USDA syntax
+ */
+export function parse_usda(text) {
+
+    // Step 1: Preprocess the raw text
+    const processed = preprocess(text);
+
+    // Step 2: Parse into a raw nested object tree
+    const tree = parse_tree(processed);
+
+    // Step 3: Walk the tree and emit specsByPath entries
+    const specs_by_path = {};
+
+    // Parse root/stage metadata
+    const root_fields = extract_stage_metadata(tree);
+    specs_by_path["/"] = { specType: SpecType.Prim, fields: root_fields };
+
+    // Walk all prim definitions
+    walk_tree(tree, "/", specs_by_path);
+
+    return { specsByPath: specs_by_path };
+}
+
+
+// ============================================================================
+// Preprocessing
+// ============================================================================
+
+/**
+ * Preprocess USDA text: strip comments, collapse multi-line values,
+ * normalize whitespace.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function preprocess(text) {
+
+    // Remove block comments /* ... */
+    text = strip_block_comments(text);
+
+    // Collapse triple-quoted strings to single lines
+    text = collapse_triple_quotes(text);
+
+    const lines = text.split("\n");
+    const result = [];
+
+    let in_multiline = false;
+    let bracket_depth = 0;
+    let accumulated = "";
+
+    for (let i = 0; i < lines.length; i++) {
+        let line = lines[i];
+
+        // Strip inline comments (preserving #usda header)
+        line = strip_inline_comment(line);
+
+        const trimmed = line.trim();
+
+        if (in_multiline) {
+            accumulated += " " + trimmed;
+
+            for (let c = 0; c < trimmed.length; c++) {
+                if (trimmed[c] === "[") bracket_depth++;
+                else if (trimmed[c] === "]") bracket_depth--;
+            }
+
+            if (bracket_depth === 0) {
+                result.push(accumulated);
+                accumulated = "";
+                in_multiline = false;
+            }
+
+        } else {
+
+            // Detect start of a multi-line array value
+            if (trimmed.includes("=")) {
+                const eq_index = find_assignment_operator(trimmed);
+
+                if (eq_index !== -1) {
+                    const rhs = trimmed.slice(eq_index + 1).trim();
+
+                    let open = 0;
+                    let close = 0;
+
+                    for (let c = 0; c < rhs.length; c++) {
+                        if (rhs[c] === "[") open++;
+                        else if (rhs[c] === "]") close++;
+                    }
+
+                    if (open > close) {
+                        in_multiline = true;
+                        bracket_depth = open - close;
+                        accumulated = trimmed;
+                        continue;
+                    }
+                }
+            }
+
+            result.push(trimmed);
+        }
+    }
+
+    return result.join("\n");
+}
+
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function strip_block_comments(text) {
+    // Use regex for O(N) performance instead of char-by-char string concatenation
+    return text.replace(/\/\*[\s\S]*?\*\//g, "");
+}
+
+
+/**
+ * Collapse triple-quoted strings (''' or \"\"\") onto single lines.
+ * @param {string} text
+ * @returns {string}
+ */
+function collapse_triple_quotes(text) {
+    const parts = [];
+    let i = 0;
+    let segment_start = 0;
+
+    while (i < text.length) {
+        if (i + 2 < text.length) {
+            const triple = text.slice(i, i + 3);
+
+            if (triple === "'''" || triple === '"""') {
+                // Flush text before this triple-quote
+                parts.push(text.slice(segment_start, i));
+                parts.push(triple);
+                i += 3;
+
+                const inner = [];
+
+                while (i < text.length) {
+                    if (i + 2 < text.length && text.slice(i, i + 3) === triple) {
+                        parts.push(inner.join(""));
+                        parts.push(triple);
+                        i += 3;
+                        break;
+                    } else if (text[i] === "\n") {
+                        inner.push("\\n");
+                    } else if (text[i] !== "\r") {
+                        inner.push(text[i]);
+                    }
+
+                    i++;
+                }
+
+                segment_start = i;
+                continue;
+            }
+        }
+
+        i++;
+    }
+
+    // Flush remaining text
+    parts.push(text.slice(segment_start));
+
+    return parts.join("");
+}
+
+
+/**
+ * Strip an inline `#` comment, respecting string boundaries.
+ * Preserves `#usda` header lines.
+ * @param {string} line
+ * @returns {string}
+ */
+function strip_inline_comment(line) {
+
+    if (line.trim().startsWith("#usda")) {
+        return line;
+    }
+
+    let in_string = false;
+    let string_char = null;
+    let escaped = false;
+
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+
+        if (ch === "\\") {
+            escaped = true;
+            continue;
+        }
+
+        if (!in_string && (ch === '"' || ch === "'")) {
+            in_string = true;
+            string_char = ch;
+        } else if (in_string && ch === string_char) {
+            in_string = false;
+            string_char = null;
+        } else if (!in_string && ch === "#") {
+            return line.slice(0, i).trimEnd();
+        }
+    }
+
+    return line;
+}
+
+
+/**
+ * Find the first `=` not inside a quoted string.
+ * @param {string} line
+ * @returns {number} Index of `=`, or -1
+ */
+function find_assignment_operator(line) {
+    let in_string = false;
+    let string_char = null;
+    let escaped = false;
+
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+
+        if (ch === "\\") {
+            escaped = true;
+            continue;
+        }
+
+        if (!in_string && (ch === '"' || ch === "'")) {
+            in_string = true;
+            string_char = ch;
+        } else if (in_string && ch === string_char) {
+            in_string = false;
+        } else if (!in_string && ch === "=") {
+            return i;
+        }
+    }
+
+    return -1;
+}
+
+
+// ============================================================================
+// Tree Parsing
+// ============================================================================
+
+/**
+ * Parse preprocessed USDA lines into a nested object tree.
+ *
+ * Each `def TypeName "name" { ... }` block becomes a keyed sub-object.
+ * Properties become key-value pairs within their owning object.
+ *
+ * @param {string} text - Preprocessed USDA text
+ * @returns {Object}
+ */
+function parse_tree(text) {
+
+    const root = {};
+    const lines = text.split("\n");
+
+    let pending_key = null;
+    let target = root;
+    const stack = [root];
+
+    for (const raw_line of lines) {
+        const line = raw_line.trim();
+
+        if (line.length === 0) {
+            continue;
+        }
+
+        if (line.includes("=")) {
+            const eq_index = find_assignment_operator(line);
+
+            if (eq_index === -1) {
+                pending_key = line;
+                continue;
+            }
+
+            const lhs = line.slice(0, eq_index).trim();
+            const rhs = line.slice(eq_index + 1).trim();
+
+            if (rhs.endsWith("{")) {
+                const group = {};
+                stack.push(group);
+                target[lhs] = group;
+                target = group;
+            } else if (rhs.endsWith("(")) {
+                // Metadata annotation block — the value stays on the key,
+                // the block's entries are stored alongside under META_KEY_SUFFIX
+                target[lhs] = rhs.slice(0, -1).trim();
+                const meta = {};
+                target[lhs + META_KEY_SUFFIX] = meta;
+                stack.push(meta);
+                target = meta;
+            } else {
+                target[lhs] = rhs;
+            }
+
+        } else if (line.includes(":") && !line.includes("=")) {
+            // Dictionary entries like "0: [(...)...]" for timeSamples
+            const colon_index = line.indexOf(":");
+            const key = line.slice(0, colon_index).trim();
+            const value = line.slice(colon_index + 1).trim();
+
+            if (/^[\d.]+$/.test(key)) {
+                target[key] = value;
+            }
+
+        } else if (line.endsWith("{")) {
+            const group = target[pending_key] || {};
+            stack.push(group);
+            target[pending_key] = group;
+            target = group;
+
+        } else if (line.endsWith("}")) {
+            stack.pop();
+
+            if (stack.length === 0) continue;
+
+            target = stack[stack.length - 1];
+
+        } else if (line.endsWith("(")) {
+            const meta = {};
+            stack.push(meta);
+            pending_key = line.split("(")[0].trim() || pending_key;
+            target[pending_key] = meta;
+            target = meta;
+
+        } else if (line.endsWith(")")) {
+            stack.pop();
+            target = stack[stack.length - 1];
+
+        } else {
+            pending_key = line;
+        }
+    }
+
+    return root;
+}
+
+
+// ============================================================================
+// Stage Metadata Extraction
+// ============================================================================
+
+/**
+ * Extract stage metadata from the `#usda 1.0` header block.
+ *
+ * @see https://openusd.org/release/api/class_usd_stage.html — Stage-level metadata
+ * @see https://openusd.org/release/api/class_usd_geom_set_stage_up_axis.html — upAxis
+ * @see https://openusd.org/release/api/class_usd_geom_linear_units.html — metersPerUnit
+ *
+ * @param {Object} tree - Parsed tree
+ * @returns {Object} Root prim fields with `upAxis`, `defaultPrim`, `metersPerUnit`
+ */
+function extract_stage_metadata(tree) {
+
+    const fields = {};
+    const header = tree["#usda 1.0"];
+
+    if (!header) {
+        return fields;
+    }
+
+    if (header.upAxis) {
+        fields.upAxis = strip_quotes(header.upAxis);
+    }
+
+    if (header.defaultPrim) {
+        fields.defaultPrim = strip_quotes(header.defaultPrim);
+    }
+
+    if (header.metersPerUnit !== undefined) {
+        fields.metersPerUnit = parseFloat(header.metersPerUnit);
+    }
+
+    if (header.doc) {
+        fields.doc = strip_quotes(header.doc);
+    }
+
+    return fields;
+}
+
+
+// ============================================================================
+// Tree Walking → specsByPath
+// ============================================================================
+
+/**
+ * Recursively walk the parsed tree and emit specsByPath entries.
+ *
+ * @param {Object} data - Current tree node
+ * @param {string} parent_path - Parent prim path
+ * @param {Object} specs_by_path - Output map (modified in place)
+ */
+function walk_tree(data, parent_path, specs_by_path) {
+
+    const prim_children = [];
+
+    for (const key in data) {
+        if (key === "#usda 1.0") continue;
+        if (key === "variants") continue;
+
+        const def_match = key.match(DEF_MATCH);
+
+        if (!def_match) continue;
+
+        const specifier = def_match[1]; // "def", "over", or "class"
+        const type_name = def_match[2] || "";
+        const name = def_match[3];
+        const path = parent_path === "/" ? "/" + name : parent_path + "/" + name;
+
+        prim_children.push(name);
+
+        const prim_fields = { typeName: type_name, specifier };
+        const prim_data = data[key];
+
+        // Extract attributes, relationships, and xformOps
+        extract_prim_data(prim_data, path, prim_fields, specs_by_path);
+
+        specs_by_path[path] = { specType: SpecType.Prim, fields: prim_fields };
+
+        // Recurse into children
+        walk_tree(prim_data, path, specs_by_path);
+    }
+
+    // Attach primChildren to parent spec
+    if (prim_children.length > 0 && specs_by_path[parent_path]) {
+        specs_by_path[parent_path].fields.primChildren = prim_children;
+    }
+}
+
+
+/**
+ * Extract attributes, relationships, and xformOps from a prim's tree data.
+ *
+ * @param {Object} data - Prim tree object
+ * @param {string} path - Prim path
+ * @param {Object} prim_fields - Prim fields to populate
+ * @param {Object} specs_by_path - Output map
+ */
+function extract_prim_data(data, path, prim_fields, specs_by_path) {
+
+    if (!data || typeof data !== "object") return;
+
+    for (const key in data) {
+
+        // Skip nested def blocks (handled by walk_tree)
+        if (key.startsWith("def ") || key.startsWith("over ") || key.startsWith("class ")) continue;
+
+        // Metadata sibling entries are consumed alongside their attribute below
+        if (key.endsWith(META_KEY_SUFFIX)) continue;
+
+        // Composition arcs — warn and skip
+        if (key === "prepend references" || key === "references") {
+            console.warn(`[USD] Composition arc "references" at ${path} is not supported, skipping`);
+            continue;
+        }
+
+        if (key === "payload") {
+            console.warn(`[USD] Composition arc "payload" at ${path} is not supported, skipping`);
+            continue;
+        }
+
+        // Relationships
+        // @see https://openusd.org/release/glossary.html#usdglossary-relationship
+        if (key.startsWith("rel ")) {
+            const rel_name = key.slice(4);
+            const rel_path = path + "." + rel_name;
+            const target = String(data[key]).replace(/[<>]/g, "");
+
+            specs_by_path[rel_path] = {
+                specType: SpecType.Relationship,
+                fields: { targetPaths: [target] }
+            };
+            continue;
+        }
+
+        // xformOpOrder
+        // @see https://openusd.org/release/api/class_usd_geom_xformable.html#details
+        if (key.includes("xformOpOrder")) {
+            prim_fields.xformOpOrder = parse_string_array(data[key]);
+            continue;
+        }
+
+        // Typed attributes
+        const attr_match = key.match(ATTR_MATCH);
+        if (!attr_match) continue;
+
+        const value_type = attr_match[2];
+        const attr_name = attr_match[3];
+        const raw_value = data[key];
+
+        // Connection attributes (e.g. "inputs:diffuseColor.connect = </path>")
+        if (attr_name.endsWith(".connect")) {
+            const base_name = attr_name.slice(0, -8);
+            const attr_path = path + "." + base_name;
+
+            let conn_path = String(raw_value).trim();
+            if (conn_path.startsWith("<")) conn_path = conn_path.slice(1);
+            if (conn_path.endsWith(">")) conn_path = conn_path.slice(0, -1);
+
+            const spec = obtain_attribute_spec(specs_by_path, attr_path, value_type);
+            spec.fields.connectionPaths = [conn_path];
+            continue;
+        }
+
+        // TimeSamples
+        if (attr_name.endsWith(".timeSamples") && typeof raw_value === "object") {
+            const base_name = attr_name.slice(0, -12);
+            const attr_path = path + "." + base_name;
+
+            const times = [];
+            const values = [];
+
+            for (const frame_key in raw_value) {
+                const frame = parseFloat(frame_key);
+                if (isNaN(frame)) continue;
+
+                times.push(frame);
+                values.push(parse_attribute_value(value_type, raw_value[frame_key]));
+            }
+
+            // Sort by time
+            const sorted = times
+                .map((t, i) => ({ t, v: values[i] }))
+                .sort((a, b) => a.t - b.t);
+
+            const spec = obtain_attribute_spec(specs_by_path, attr_path, value_type);
+            spec.fields.timeSamples = {
+                times: sorted.map(s => s.t),
+                values: sorted.map(s => s.v)
+            };
+            continue;
+        }
+
+        // Regular attribute
+        let value_text = raw_value;
+
+        // Block-form metadata (`= value (\n ... \n)`) is stored by parse_tree
+        // under the META_KEY_SUFFIX sibling key
+        let meta = data[key + META_KEY_SUFFIX];
+
+        // Single-line form: `= value ( interpolation = "faceVarying" )` — the
+        // metadata rides inside the value text and must be split off before
+        // value parsing
+        if (typeof raw_value === "string") {
+            const split = split_inline_metadata(raw_value);
+
+            value_text = split.value;
+
+            if (split.meta !== null) {
+                meta = split.meta;
+            }
+        }
+
+        const parsed_value = parse_attribute_value(value_type, value_text);
+        const attr_path = path + "." + attr_name;
+
+        const spec = obtain_attribute_spec(specs_by_path, attr_path, value_type);
+        spec.fields.default = parsed_value;
+
+        if (meta !== undefined) {
+            spec.fields.metadata = meta;
+
+            // @see https://openusd.org/release/glossary.html#usdglossary-interpolation
+            if (meta.interpolation !== undefined) {
+                spec.fields.interpolation = strip_quotes(String(meta.interpolation));
+            }
+        }
+    }
+}
+
+
+/**
+ * Get or create an attribute spec, merging field updates into an existing
+ * entry. USDA authors one field per line (`.connect`, `.timeSamples`, the
+ * default value) — a later line must not clobber fields set by earlier ones.
+ *
+ * @param {Object} specs_by_path
+ * @param {string} attr_path
+ * @param {string} value_type
+ * @returns {{ specType: number, fields: Object }}
+ */
+function obtain_attribute_spec(specs_by_path, attr_path, value_type) {
+
+    let spec = specs_by_path[attr_path];
+
+    if (spec === undefined) {
+        spec = {
+            specType: SpecType.Attribute,
+            fields: { typeName: value_type }
+        };
+
+        specs_by_path[attr_path] = spec;
+    } else if (spec.fields.typeName === undefined) {
+        spec.fields.typeName = value_type;
+    }
+
+    return spec;
+}
+
+
+// ============================================================================
+// Value Parsing
+// ============================================================================
+
+/**
+ * Parse a raw USDA attribute value string into a typed JS value.
+ *
+ * @param {string} value_type - USD type name (e.g. "float3[]", "token", "asset")
+ * @param {*} raw - Raw string or already-parsed value
+ * @returns {*} Parsed value (number, array, string, etc.)
+ */
+function parse_attribute_value(value_type, raw) {
+
+    if (raw === undefined || raw === null) return undefined;
+
+    const str = String(raw).trim();
+
+    // Array types
+    if (value_type.endsWith("[]")) {
+        return parse_array_value(value_type, str);
+    }
+
+    // Quaternion types — stored in USD's native (w, x, y, z) order.
+    // Conversion to the engine's (x, y, z, w) is done in usd_compose_transform
+    // when the quaternion is consumed for matrix composition.
+    // @see https://openusd.org/release/api/class_gf_quatf.html — GfQuatf real-part-first layout
+    if (value_type.startsWith("quat")) {
+        const cleaned = str.replace(/[()]/g, "");
+        return cleaned.split(",").map(s => parseFloat(s.trim()));
+    }
+
+    // Vector types (float2, float3, float4, double3, point3f, color3f, normal3f, etc.)
+    if (/\d/.test(value_type) && (
+        value_type.includes("float") || value_type.includes("double") ||
+        value_type.includes("int") || value_type.startsWith("point") ||
+        value_type.startsWith("color") || value_type.startsWith("normal") ||
+        value_type.startsWith("texCoord") || value_type.startsWith("vec")
+    )) {
+        const cleaned = str.replace(/[()]/g, "");
+        return cleaned.split(",").map(s => parseFloat(s.trim()));
+    }
+
+    // Matrix types
+    if (value_type.includes("matrix")) {
+        const cleaned = str.replace(/[()]/g, "");
+        return cleaned.split(",").map(s => parseFloat(s.trim()));
+    }
+
+    // Scalar numeric types
+    if (value_type === "float" || value_type === "double" || value_type === "half") {
+        return parseFloat(str);
+    }
+
+    if (value_type === "int") {
+        return parseInt(str, 10);
+    }
+
+    if (value_type === "bool") {
+        return str === "true" || str === "1";
+    }
+
+    // Asset path
+    if (value_type === "asset") {
+        return str.replace(/@/g, "").replace(/"/g, "");
+    }
+
+    // String / token
+    if (value_type === "string" || value_type === "token") {
+        return strip_quotes(str);
+    }
+
+    // Fallback
+    return strip_quotes(str);
+}
+
+
+/**
+ * Parse a USDA array value string.
+ *
+ * Handles `[(1, 2, 3), (4, 5, 6)]` → flat `[1, 2, 3, 4, 5, 6]`
+ * and simple `[1, 2, 3]` → `[1, 2, 3]`
+ *
+ * @param {string} value_type - USD array type (e.g. "float3[]")
+ * @param {string} str - Raw value string
+ * @returns {number[]|string[]}
+ */
+function parse_array_value(value_type, str) {
+
+    try {
+        // Replace USDA tuple parens with JSON brackets, strip trailing comma
+        let cleaned = str.replace(/\(/g, "[").replace(/\)/g, "]");
+
+        if (cleaned.endsWith(",")) {
+            cleaned = cleaned.slice(0, -1);
+        }
+
+        const parsed = JSON.parse(cleaned);
+
+        // Flatten nested arrays for vector types: [[1,2,3],[4,5,6]] → [1,2,3,4,5,6]
+        if (Array.isArray(parsed) && parsed.length > 0 && Array.isArray(parsed[0])) {
+            return parsed.flat();
+        }
+
+        return parsed;
+    } catch (_) {
+        // Fallback: simple split parsing
+        const cleaned = str.replace(/[\[\]]/g, "");
+
+        return cleaned.split(",").map(s => {
+            const trimmed = s.trim();
+            const num = parseFloat(trimmed);
+            return isNaN(num) ? strip_quotes(trimmed) : num;
+        });
+    }
+}
+
+
+/**
+ * Split a single-line attribute value of the form `value ( meta )` into the
+ * value text and parsed metadata entries.
+ *
+ * The metadata block is a top-level parenthesized group that FOLLOWS the
+ * value — for tuple values the leading `(...)` group is the value itself,
+ * so only a `(` seen at depth 0 after a complete value token starts metadata.
+ *
+ * @param {string} str - Trimmed raw value text
+ * @returns {{ value: string, meta: Object.<string, string>|null }}
+ */
+function split_inline_metadata(str) {
+
+    let depth = 0;
+    let in_string = false;
+    let string_char = null;
+    let escaped = false;
+    let seen_value = false;
+
+    for (let i = 0; i < str.length; i++) {
+        const ch = str[i];
+
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+
+        if (ch === "\\") {
+            escaped = true;
+            continue;
+        }
+
+        if (in_string) {
+            if (ch === string_char) {
+                in_string = false;
+            }
+            continue;
+        }
+
+        if (ch === '"' || ch === "'") {
+            in_string = true;
+            string_char = ch;
+            seen_value = true;
+        } else if (ch === "(") {
+            if (depth === 0 && seen_value) {
+                // Metadata block start — everything before it is the value
+                const meta_text = str.slice(i + 1, str.lastIndexOf(")"));
+
+                return {
+                    value: str.slice(0, i).trim(),
+                    meta: parse_metadata_entries(meta_text)
+                };
+            }
+
+            depth++;
+            seen_value = true;
+        } else if (ch === "[") {
+            depth++;
+            seen_value = true;
+        } else if (ch === ")" || ch === "]") {
+            depth--;
+        } else if (!/\s/.test(ch)) {
+            seen_value = true;
+        }
+    }
+
+    return { value: str, meta: null };
+}
+
+
+/**
+ * Parse metadata block entries (`name = value`, separated by newlines or
+ * semicolons) into an object. Values keep their raw text (quotes intact)
+ * to mirror parse_tree's metadata-block representation.
+ *
+ * @param {string} text
+ * @returns {Object.<string, string>}
+ */
+function parse_metadata_entries(text) {
+
+    const meta = {};
+
+    META_ENTRY_MATCH.lastIndex = 0;
+
+    let m;
+    while ((m = META_ENTRY_MATCH.exec(text)) !== null) {
+        meta[m[1]] = m[2];
+    }
+
+    return meta;
+}
+
+
+/**
+ * Parse a string array value like `["xformOp:translate", "xformOp:scale"]`.
+ *
+ * @param {string} raw
+ * @returns {string[]}
+ */
+function parse_string_array(raw) {
+    const str = String(raw);
+
+    return str
+        .replace(/[\[\]]/g, "")
+        .split(",")
+        .map(s => s.trim().replace(/"/g, ""))
+        .filter(s => s.length > 0);
+}
+
+
+/**
+ * Remove surrounding quotes from a string value.
+ * @param {string} str
+ * @returns {string}
+ */
+function strip_quotes(str) {
+    if ((str.startsWith('"') && str.endsWith('"')) ||
+        (str.startsWith("'") && str.endsWith("'"))) {
+        return str.slice(1, -1);
+    }
+
+    return str;
+}