@dereekb/dbx-cli 13.19.0 → 13.20.0

package/index.cjs.js

@@ -57227,17 +57227,38 @@ function _array_like_to_array$3(arr, len) {
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
     return arr2;
 }
-function _array_without_holes$1(arr) {
-    if (Array.isArray(arr)) return _array_like_to_array$3(arr);
+function _array_with_holes$1(arr) {
+    if (Array.isArray(arr)) return arr;
 }
-function _iterable_to_array$1(iter) {
-    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+function _iterable_to_array_limit$1(arr, i) {
+    var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"];
+    if (_i == null) return;
+    var _arr = [];
+    var _n = true;
+    var _d = false;
+    var _s, _e;
+    try {
+        for(_i = _i.call(arr); !(_n = (_s = _i.next()).done); _n = true){
+            _arr.push(_s.value);
+            if (i && _arr.length === i) break;
+        }
+    } catch (err) {
+        _d = true;
+        _e = err;
+    } finally{
+        try {
+            if (!_n && _i["return"] != null) _i["return"]();
+        } finally{
+            if (_d) throw _e;
+        }
+    }
+    return _arr;
 }
-function _non_iterable_spread$1() {
-    throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+function _non_iterable_rest$1() {
+    throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
-function _to_consumable_array$1(arr) {
-    return _array_without_holes$1(arr) || _iterable_to_array$1(arr) || _unsupported_iterable_to_array$3(arr) || _non_iterable_spread$1();
+function _sliced_to_array$1(arr, i) {
+    return _array_with_holes$1(arr) || _iterable_to_array_limit$1(arr, i) || _unsupported_iterable_to_array$3(arr, i) || _non_iterable_rest$1();
 }
 function _unsupported_iterable_to_array$3(o, minLen) {
     if (!o) return;
@@ -57248,74 +57269,93 @@ function _unsupported_iterable_to_array$3(o, minLen) {
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$3(o, minLen);
 }
 /**
- * Builds a parent-linked {@link RouteTree} from a flat list of {@link RouteNode}s.
- *
- * Linkage strategy:
+ * Pure URL ↔ route matcher, shared by the dev-server `dbx_route_resolve_url`
+ * tool and (mirrored, not imported) by the firebase-server/mcp `url-models`
+ * runtime tool.
  *
- *   1. Use the explicit `parent` field if present.
- *   2. Otherwise derive parent from the dot-prefix of `name`. State `a.b.c`
- *      becomes a child of `a.b`. Trailing `.**` is stripped before lookup.
- *   3. Nodes whose parent doesn't resolve are reported as orphan warnings and
- *      placed at the tree root.
+ * No ts-morph, no node:fs — operates on a flat list of candidates each carrying
+ * a composed `fullUrl` and an opaque `value`. Matching mirrors UIRouter's
+ * literal-then-param preference: a literal segment-for-segment match wins over a
+ * parameterised one, and ties at either tier collapse to an `ambiguous` result.
+ */ /**
+ * Collapses an empty pathname to `/` and strips a single trailing slash so
+ * `/a/b/` and `/a/b` compare equal.
  *
- * Issues surfaced:
+ * @param pathname - The raw pathname to normalize.
+ * @returns The normalized pathname.
+ */ function normalizePathname(pathname) {
+    var result;
+    if (pathname.length === 0) {
+        result = '/';
+    } else if (pathname.length > 1 && pathname.endsWith('/')) {
+        result = pathname.slice(0, -1);
+    } else {
+        result = pathname;
+    }
+    return result;
+}
+/**
+ * Strips a UIRouter query string (`?…`) and/or hash (`#…`) suffix off a URL or
+ * URL pattern, keeping only the path portion. Mirrors the runtime
+ * `parseUrlModelsPathname` normalization (`firebase-server/mcp`) so build-time
+ * param extraction and runtime matching agree: a state url like
+ * `/:schoolJob?slotIndex` reduces to `/:schoolJob` rather than leaking the
+ * `?slotIndex` query param into the last path segment.
  *
- *   - `DUPLICATE_STATE_NAME` — error; second declaration is dropped.
- *   - `CYCLE_DETECTED` — error; the cycle is broken by reverting the tail to
- *     the root list.
- *   - `ORPHAN_STATE` — warning.
- */ /**
- * Builds the parent-child UIRouter tree from a flat node list, computing each
- * state's full URL while preserving any extraction issues so callers see one
- * combined diagnostics view.
+ * @param url - The URL or composed URL pattern to normalize.
+ * @returns The url with any `?…` / `#…` suffix removed.
+ */ function stripUrlQueryAndHash(url) {
+    var hashStripped = url.split('#', 1)[0];
+    return hashStripped.split('?', 1)[0];
+}
+/**
+ * Splits a path into its non-empty segments (the leading slash is dropped).
  *
- * @param nodes - The flat route nodes extracted from sources.
- * @param extractIssues - Issues already discovered during extraction to forward.
- * @returns The constructed tree alongside the merged issue list.
+ * @param path - The path or URL pattern to split.
+ * @returns The ordered segment list, empty for `/`.
+ */ function splitSegments(path) {
+    var normalized = path.startsWith('/') ? path.slice(1) : path;
+    return normalized.length === 0 ? [] : normalized.split('/');
+}
+/**
+ * Whether a composed URL contains at least one `:param` or `{param}` segment.
  *
- * @__NO_SIDE_EFFECTS__
- */ function buildRouteTree(nodes, extractIssues) {
-    var issues = _to_consumable_array$1(extractIssues);
-    var byName = new Map();
-    insertNodes(nodes, byName, issues);
-    wireParentLinks(byName, issues);
-    detectCycles(byName, issues);
-    composeFullUrls(byName);
-    var roots = collectRoots(byName);
-    sortChildren(byName, roots);
-    var _freezeTree = freezeTree(roots), frozen = _freezeTree.frozen, frozenRoots = _freezeTree.frozenRoots;
-    var result = {
-        roots: frozenRoots,
-        byName: frozen,
-        issues: issues,
-        filesChecked: 0,
-        nodeCount: byName.size
-    };
-    return result;
+ * @param path - The composed URL pattern.
+ * @returns `true` when the pattern declares a parameter.
+ */ function hasParamSegment(path) {
+    return path.includes(':') || path.includes('{');
 }
-// (1) Insert nodes; report duplicates
-function insertNodes(nodes, byName, issues) {
+/**
+ * Attempts a segment-for-segment match of a route pattern against concrete
+ * input segments. `:name` and `{name}` / `{name:type}` segments capture the
+ * input value (URL-decoded); literal segments must match exactly.
+ *
+ * @param route - The route pattern's segments.
+ * @param input - The concrete URL's segments.
+ * @returns The captured params when every segment matches, else `undefined`.
+ */ function tryMatchSegments(route, input) {
+    if (route.length !== input.length) {
+        return undefined;
+    }
+    var params = {};
+    var result = params;
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
-        for(var _iterator = nodes[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
-            var node = _step.value;
-            if (byName.has(node.name)) {
-                issues.push({
-                    code: 'DUPLICATE_STATE_NAME',
-                    severity: 'error',
-                    message: "State `".concat(node.name, "` is declared in multiple places. Keeping the first declaration."),
-                    file: node.file,
-                    line: node.line,
-                    stateName: node.name
-                });
-                continue;
+        for(var _iterator = route.entries()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var _step_value = _sliced_to_array$1(_step.value, 2), i = _step_value[0], r = _step_value[1];
+            var v = input[i];
+            if (r.startsWith(':')) {
+                var key = r.slice(1);
+                params[key] = decodeURIComponent(v);
+            } else if (r.startsWith('{') && r.endsWith('}')) {
+                var inner = r.slice(1, -1);
+                var colonIdx = inner.indexOf(':');
+                var key1 = colonIdx >= 0 ? inner.slice(0, colonIdx) : inner;
+                params[key1] = decodeURIComponent(v);
+            } else if (r !== v) {
+                result = undefined;
+                break;
             }
-            byName.set(node.name, {
-                data: node,
-                fullUrl: undefined,
-                parent: undefined,
-                children: []
-            });
         }
     } catch (err) {
         _didIteratorError = true;
@@ -57331,29 +57371,32 @@ function insertNodes(nodes, byName, issues) {
             }
         }
     }
+    return result;
 }
-// (2) Wire parent links
-function wireParentLinks(byName, issues) {
+/**
+ * Extracts param-name segments from a composed UIRouter URL. Recognises:
+ * - `:name` (Express-style)
+ * - `{name}` (UIRouter type-less)
+ * - `{name:type}` and `{name:regex}` (UIRouter typed / regex)
+ * Order is preserved; duplicates are de-duplicated by first occurrence.
+ *
+ * @param fullUrl - Composed URL (e.g. `/{orgId}/users/:userId`) or undefined.
+ * @returns The param key list in declaration order, or an empty array.
+ */ function extractUrlParamKeys(fullUrl) {
+    if (fullUrl === undefined || fullUrl.length === 0) {
+        return [];
+    }
+    var seen = new Set();
+    var keys = [];
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
-        for(var _iterator = byName.values()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
-            var treeNode = _step.value;
-            var parentName = resolveParentName(treeNode.data, byName);
-            if (!parentName) continue;
-            var parent = byName.get(parentName);
-            if (!parent) {
-                issues.push({
-                    code: 'ORPHAN_STATE',
-                    severity: 'warning',
-                    message: "State `".concat(treeNode.data.name, "` references parent `").concat(parentName, "` which is not declared in the analyzed sources."),
-                    file: treeNode.data.file,
-                    line: treeNode.data.line,
-                    stateName: treeNode.data.name
-                });
-                continue;
+        for(var _iterator = fullUrl.split('/')[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var segment = _step.value;
+            var key = extractParamKeyFromSegment(segment);
+            if (key !== undefined && !seen.has(key)) {
+                seen.add(key);
+                keys.push(key);
             }
-            treeNode.parent = parent;
-            parent.children.push(treeNode);
         }
     } catch (err) {
         _didIteratorError = true;
@@ -57369,17 +57412,67 @@ function wireParentLinks(byName, issues) {
             }
         }
     }
+    return keys;
 }
-// (3) Detect cycles. A cycle is impossible via dot-prefix linkage but the
-// explicit `parent` field can introduce one (`a.parent = 'b'`,
-// `b.parent = 'a'`). Walk from each node and break the chain on revisits.
-function detectCycles(byName, issues) {
+function extractParamKeyFromSegment(rawSegment) {
+    // Defense-in-depth: a `:param?query` / `:param#hash` segment that slips past
+    // `composeFullUrl` normalization must not leak its suffix into the param key.
+    var segment = stripUrlQueryAndHash(rawSegment);
+    if (segment.startsWith(':')) {
+        var key = segment.slice(1);
+        return key.length > 0 ? key : undefined;
+    }
+    if (segment.startsWith('{') && segment.endsWith('}')) {
+        var inner = segment.slice(1, -1);
+        var colonIdx = inner.indexOf(':');
+        var rawKey = colonIdx >= 0 ? inner.slice(0, colonIdx) : inner;
+        var key1 = rawKey.trim();
+        return key1.length > 0 ? key1 : undefined;
+    }
+    return undefined;
+}
+/**
+ * Matches a pathname against a flat candidate list, preferring a literal
+ * (exact composed-URL) match over a parameterised one. A tie at either tier
+ * collapses to `ambiguous`; otherwise the closest near-misses are scored and
+ * returned in a `none` result.
+ *
+ * @param input - The candidate entries and the pathname to resolve.
+ * @returns A discriminated match / ambiguous / none result.
+ */ function matchUrlAgainstEntries(input) {
+    var pathname = normalizePathname(input.pathname);
+    var literal = matchLiteral(input.entries, pathname);
+    var result;
+    if (literal.length === 1) {
+        var _literal__fullUrl;
+        result = {
+            kind: 'match',
+            via: 'literal',
+            value: literal[0].value,
+            matchedFullUrl: normalizePathname((_literal__fullUrl = literal[0].fullUrl) !== null && _literal__fullUrl !== void 0 ? _literal__fullUrl : pathname),
+            params: {}
+        };
+    } else if (literal.length > 1) {
+        result = {
+            kind: 'ambiguous',
+            values: literal.map(function(e) {
+                return e.value;
+            })
+        };
+    } else {
+        result = matchParamOrNone(input.entries, pathname);
+    }
+    return result;
+}
+function matchLiteral(entries, pathname) {
+    var out = [];
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
-        for(var _iterator = byName.values()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
-            var treeNode = _step.value;
-            if (!treeNode.parent) continue;
-            detectCycleFor(treeNode, issues);
+        for(var _iterator = entries[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var entry = _step.value;
+            if (entry.fullUrl !== undefined && normalizePathname(entry.fullUrl) === pathname) {
+                out.push(entry);
+            }
         }
     } catch (err) {
         _didIteratorError = true;
@@ -57395,45 +57488,25 @@ function detectCycles(byName, issues) {
             }
         }
     }
+    return out;
 }
-function detectCycleFor(treeNode, issues) {
-    var seen = new Set();
-    seen.add(treeNode.data.name);
-    var cursor = treeNode.parent;
-    while(cursor){
-        if (seen.has(cursor.data.name)) {
-            issues.push({
-                code: 'CYCLE_DETECTED',
-                severity: 'error',
-                message: "Cycle detected involving `".concat(treeNode.data.name, "` and `").concat(cursor.data.name, "`. Severing the parent link."),
-                file: treeNode.data.file,
-                line: treeNode.data.line,
-                stateName: treeNode.data.name
-            });
-            detachFromParent(treeNode);
-            return;
-        }
-        seen.add(cursor.data.name);
-        cursor = cursor.parent;
-    }
-}
-function detachFromParent(treeNode) {
-    if (!treeNode.parent) return;
-    var idx = treeNode.parent.children.indexOf(treeNode);
-    if (idx >= 0) {
-        treeNode.parent.children.splice(idx, 1);
-    }
-    treeNode.parent = undefined;
-}
-// (4) Compose full URLs (parent walk; root url is not prefixed). UIRouter's
-// own logic is more nuanced (some states overwrite their parent's URL with
-// a leading `^`), but this gives a useful approximation for the common case.
-function composeFullUrls(byName) {
+function matchParamOrNone(entries, pathname) {
+    var inputSegments = splitSegments(pathname);
+    var hits = [];
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
-        for(var _iterator = byName.values()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
-            var treeNode = _step.value;
-            treeNode.fullUrl = composeFullUrl(treeNode);
+        for(var _iterator = entries[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var entry = _step.value;
+            if (entry.fullUrl === undefined || !hasParamSegment(entry.fullUrl)) {
+                continue;
+            }
+            var params = tryMatchSegments(splitSegments(entry.fullUrl), inputSegments);
+            if (params) {
+                hits.push({
+                    entry: entry,
+                    params: params
+                });
+            }
         }
     } catch (err) {
         _didIteratorError = true;
@@ -57449,42 +57522,67 @@ function composeFullUrls(byName) {
             }
         }
     }
+    var result;
+    if (hits.length === 1) {
+        var _hits__entry_fullUrl;
+        result = {
+            kind: 'match',
+            via: 'param',
+            value: hits[0].entry.value,
+            matchedFullUrl: normalizePathname((_hits__entry_fullUrl = hits[0].entry.fullUrl) !== null && _hits__entry_fullUrl !== void 0 ? _hits__entry_fullUrl : pathname),
+            params: hits[0].params
+        };
+    } else if (hits.length > 1) {
+        result = {
+            kind: 'ambiguous',
+            values: hits.map(function(h) {
+                return h.entry.value;
+            })
+        };
+    } else {
+        result = {
+            kind: 'none',
+            candidates: scoreCandidates(entries, pathname)
+        };
+    }
+    return result;
 }
-// (5) Identify roots
-function collectRoots(byName) {
-    var roots = [];
+/**
+ * Scores every candidate by shared leading segments (literal segment = 2,
+ * param segment = 1, mismatch stops scoring) and returns the top 5 values.
+ *
+ * @param entries - The candidate entries to score.
+ * @param pathname - The pathname being resolved.
+ * @returns Up to five closest candidate values, best first.
+ */ function scoreCandidates(entries, pathname) {
+    var segments = splitSegments(normalizePathname(pathname));
+    var scored = [];
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
-        for(var _iterator = byName.values()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
-            var treeNode = _step.value;
-            if (!treeNode.parent) {
-                roots.push(treeNode);
+        for(var _iterator = entries[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var entry = _step.value;
+            if (entry.fullUrl === undefined) {
+                continue;
             }
-        }
-    } catch (err) {
-        _didIteratorError = true;
-        _iteratorError = err;
-    } finally{
-        try {
-            if (!_iteratorNormalCompletion && _iterator.return != null) {
-                _iterator.return();
+            var candidateSegments = splitSegments(entry.fullUrl);
+            var score = 0;
+            var maxIndex = Math.min(segments.length, candidateSegments.length);
+            for(var i = 0; i < maxIndex; i += 1){
+                if (segments[i] === candidateSegments[i]) {
+                    score += 2;
+                } else if (candidateSegments[i].startsWith(':') || candidateSegments[i].startsWith('{')) {
+                    score += 1;
+                } else {
+                    break;
+                }
             }
-        } finally{
-            if (_didIteratorError) {
-                throw _iteratorError;
+            if (score > 0) {
+                scored.push({
+                    value: entry.value,
+                    score: score
+                });
             }
         }
-    }
-    return roots;
-}
-// (6) Sort children deterministically by name
-function sortChildren(byName, roots) {
-    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
-    try {
-        for(var _iterator = byName.values()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
-            var treeNode = _step.value;
-            treeNode.children.sort(compareByName);
-        }
     } catch (err) {
         _didIteratorError = true;
         _iteratorError = err;
@@ -57499,133 +57597,91 @@ function sortChildren(byName, roots) {
             }
         }
     }
-    roots.sort(compareByName);
+    scored.sort(function(a, b) {
+        return b.score - a.score;
+    });
+    return scored.slice(0, 5).map(function(s) {
+        return s.value;
+    });
 }
-// (7) Freeze: convert MutableTreeNode → RouteTreeNode (children: readonly).
-function freezeTree(roots) {
-    var frozen = new Map();
-    var freeze = function freeze1(mut) {
-        var existing = frozen.get(mut.data.name);
-        if (existing) return existing;
-        var placeholder = {
-            data: mut.data,
-            fullUrl: mut.fullUrl,
-            parent: undefined,
-            children: []
-        };
-        frozen.set(mut.data.name, placeholder);
-        placeholder.parent = mut.parent ? freeze(mut.parent) : undefined;
-        placeholder.children = mut.children.map(freeze);
-        return placeholder;
-    };
-    var frozenRoots = roots.map(freeze);
-    return {
-        frozen: frozen,
-        frozenRoots: frozenRoots
-    };
+
+function _array_like_to_array$2(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
 }
-function resolveParentName(node, byName) {
-    if (node.explicitParent) {
-        return node.explicitParent;
-    }
-    var lookupName = node.name.endsWith('.**') ? node.name.slice(0, -3) : node.name;
-    var lastDot = lookupName.lastIndexOf('.');
-    if (lastDot < 0) {
-        return undefined;
-    }
-    var candidate = lookupName.slice(0, lastDot);
-    // Confirm the candidate exists; otherwise fall back to undefined so the
-    // orphan check fires.
-    if (byName.has(candidate)) {
-        return candidate;
-    }
-    // Even if the candidate doesn't exist, return it so the orphan logic can
-    // surface an informative message.
-    return candidate;
+function _array_without_holes$1(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$2(arr);
 }
-function composeFullUrl(node) {
-    var segments = [];
-    var cursor = node;
-    while(cursor){
-        if (cursor.data.url !== undefined) {
-            segments.unshift(cursor.data.url);
-        }
-        cursor = cursor.parent;
-    }
-    if (segments.length === 0) {
-        return undefined;
-    }
-    // Join segments and collapse double slashes (root url '/' followed by
-    // child '/foo' would otherwise yield '//foo').
-    var joined = segments.join('');
-    var collapsed = joined.replaceAll(/\/{2,}/g, '/');
-    return collapsed.length === 0 ? '/' : collapsed;
+function _iterable_to_array$1(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
 }
-function compareByName(a, b) {
-    if (a.data.name < b.data.name) {
-        return -1;
-    }
-    if (a.data.name > b.data.name) {
-        return 1;
-    }
-    return 0;
+function _non_iterable_spread$1() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _to_consumable_array$1(arr) {
+    return _array_without_holes$1(arr) || _iterable_to_array$1(arr) || _unsupported_iterable_to_array$2(arr) || _non_iterable_spread$1();
+}
+function _unsupported_iterable_to_array$2(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array$2(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$2(o, minLen);
 }
-
 /**
- * Walks every supplied source through the extractor and emits a flat node and
- * issue list, used when the caller has already gathered a complete glob/file
- * set in memory.
+ * Builds the parent-child UIRouter tree from a flat node list, computing each
+ * state's full URL while preserving any extraction issues so callers see one
+ * combined diagnostics view.
  *
- * @param sources - The in-memory sources to extract from.
- * @returns The merged extraction nodes, issues, and processed file count.
- */ function resolveRouteSources(sources) {
-    var nodes = [];
-    var issues = [];
+ * @param nodes - The flat route nodes extracted from sources.
+ * @param extractIssues - Issues already discovered during extraction to forward.
+ * @returns The constructed tree alongside the merged issue list.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */ function buildRouteTree(nodes, extractIssues) {
+    var issues = _to_consumable_array$1(extractIssues);
+    var byName = new Map();
+    insertNodes(nodes, byName, issues);
+    wireParentLinks(byName, issues);
+    detectCycles(byName, issues);
+    composeFullUrls(byName);
+    var roots = collectRoots(byName);
+    sortChildren(byName, roots);
+    var _freezeTree = freezeTree(roots), frozen = _freezeTree.frozen, frozenRoots = _freezeTree.frozenRoots;
+    var result = {
+        roots: frozenRoots,
+        byName: frozen,
+        issues: issues,
+        filesChecked: 0,
+        nodeCount: byName.size
+    };
+    return result;
+}
+// (1) Insert nodes; report duplicates
+function insertNodes(nodes, byName, issues) {
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
-        for(var _iterator = sources[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
-            var source = _step.value;
-            var extracted = extractFile(source);
-            var _iteratorNormalCompletion1 = true, _didIteratorError1 = false, _iteratorError1 = undefined;
-            try {
-                for(var _iterator1 = extracted.nodes[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true){
-                    var node = _step1.value;
-                    nodes.push(node);
-                }
-            } catch (err) {
-                _didIteratorError1 = true;
-                _iteratorError1 = err;
-            } finally{
-                try {
-                    if (!_iteratorNormalCompletion1 && _iterator1.return != null) {
-                        _iterator1.return();
-                    }
-                } finally{
-                    if (_didIteratorError1) {
-                        throw _iteratorError1;
-                    }
-                }
-            }
-            var _iteratorNormalCompletion2 = true, _didIteratorError2 = false, _iteratorError2 = undefined;
-            try {
-                for(var _iterator2 = extracted.issues[Symbol.iterator](), _step2; !(_iteratorNormalCompletion2 = (_step2 = _iterator2.next()).done); _iteratorNormalCompletion2 = true){
-                    var issue = _step2.value;
-                    issues.push(issue);
-                }
-            } catch (err) {
-                _didIteratorError2 = true;
-                _iteratorError2 = err;
-            } finally{
-                try {
-                    if (!_iteratorNormalCompletion2 && _iterator2.return != null) {
-                        _iterator2.return();
-                    }
-                } finally{
-                    if (_didIteratorError2) {
-                        throw _iteratorError2;
-                    }
-                }
+        for(var _iterator = nodes[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var node = _step.value;
+            if (byName.has(node.name)) {
+                issues.push({
+                    code: 'DUPLICATE_STATE_NAME',
+                    severity: 'error',
+                    message: "State `".concat(node.name, "` is declared in multiple places. Keeping the first declaration."),
+                    file: node.file,
+                    line: node.line,
+                    stateName: node.name
+                });
+                continue;
             }
+            byName.set(node.name, {
+                data: node,
+                fullUrl: undefined,
+                parent: undefined,
+                children: []
+            });
         }
     } catch (err) {
         _didIteratorError = true;
@@ -57641,28 +57697,29 @@ function compareByName(a, b) {
             }
         }
     }
-    var result = {
-        nodes: nodes,
-        issues: issues,
-        filesChecked: sources.length
-    };
-    return result;
 }
-/**
- * Returns the relative module specifiers imported by `source` — used to plan
- * the next round of file reads in transitive walking. Specifiers are
- * left untouched (no `.ts` resolution); the caller normalizes them.
- *
- * @param source - The in-memory source to inspect.
- * @returns The relative specifiers in original-source order.
- */ function computeRelativeSpecifiers(source) {
-    var extracted = extractFile(source);
-    var out = [];
+// (2) Wire parent links
+function wireParentLinks(byName, issues) {
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
-        for(var _iterator = extracted.importedFromRelative[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
-            var imp = _step.value;
-            out.push(imp.moduleSpecifier);
+        for(var _iterator = byName.values()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var treeNode = _step.value;
+            var parentName = resolveParentName(treeNode.data, byName);
+            if (!parentName) continue;
+            var parent = byName.get(parentName);
+            if (!parent) {
+                issues.push({
+                    code: 'ORPHAN_STATE',
+                    severity: 'warning',
+                    message: "State `".concat(treeNode.data.name, "` references parent `").concat(parentName, "` which is not declared in the analyzed sources."),
+                    file: treeNode.data.file,
+                    line: treeNode.data.line,
+                    stateName: treeNode.data.name
+                });
+                continue;
+            }
+            treeNode.parent = parent;
+            parent.children.push(treeNode);
         }
     } catch (err) {
         _didIteratorError = true;
@@ -57678,148 +57735,71 @@ function compareByName(a, b) {
             }
         }
     }
-    return out;
-}
-
-/**
- * Pure tree-loading entry point. Resolves the supplied source list and builds
- * the parent/child tree in one step so callers can stay thin.
- *
- * @param args - The in-memory sources to process.
- * @returns The constructed route tree with extraction issues attached.
- */ function loadRouteTree(args) {
-    var resolved = resolveRouteSources(args.sources);
-    var tree = buildRouteTree(resolved.nodes, resolved.issues);
-    var result = {
-        roots: tree.roots,
-        byName: tree.byName,
-        issues: tree.issues,
-        filesChecked: resolved.filesChecked,
-        nodeCount: tree.nodeCount
-    };
-    return result;
-}
-
-function _array_like_to_array$2(arr, len) {
-    if (len == null || len > arr.length) len = arr.length;
-    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
-    return arr2;
-}
-function _array_with_holes$1(arr) {
-    if (Array.isArray(arr)) return arr;
 }
-function _iterable_to_array_limit$1(arr, i) {
-    var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"];
-    if (_i == null) return;
-    var _arr = [];
-    var _n = true;
-    var _d = false;
-    var _s, _e;
+// (3) Detect cycles. A cycle is impossible via dot-prefix linkage but the
+// explicit `parent` field can introduce one (`a.parent = 'b'`,
+// `b.parent = 'a'`). Walk from each node and break the chain on revisits.
+function detectCycles(byName, issues) {
+    var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
-        for(_i = _i.call(arr); !(_n = (_s = _i.next()).done); _n = true){
-            _arr.push(_s.value);
-            if (i && _arr.length === i) break;
+        for(var _iterator = byName.values()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var treeNode = _step.value;
+            if (!treeNode.parent) continue;
+            detectCycleFor(treeNode, issues);
         }
     } catch (err) {
-        _d = true;
-        _e = err;
+        _didIteratorError = true;
+        _iteratorError = err;
     } finally{
         try {
-            if (!_n && _i["return"] != null) _i["return"]();
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+                _iterator.return();
+            }
         } finally{
-            if (_d) throw _e;
+            if (_didIteratorError) {
+                throw _iteratorError;
+            }
         }
     }
-    return _arr;
-}
-function _non_iterable_rest$1() {
-    throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
-function _sliced_to_array$1(arr, i) {
-    return _array_with_holes$1(arr) || _iterable_to_array_limit$1(arr, i) || _unsupported_iterable_to_array$2(arr, i) || _non_iterable_rest$1();
-}
-function _unsupported_iterable_to_array$2(o, minLen) {
-    if (!o) return;
-    if (typeof o === "string") return _array_like_to_array$2(o, minLen);
-    var n = Object.prototype.toString.call(o).slice(8, -1);
-    if (n === "Object" && o.constructor) n = o.constructor.name;
-    if (n === "Map" || n === "Set") return Array.from(n);
-    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$2(o, minLen);
-}
-/**
- * Pure URL ↔ route matcher, shared by the dev-server `dbx_route_resolve_url`
- * tool and (mirrored, not imported) by the firebase-server/mcp `url-models`
- * runtime tool.
- *
- * No ts-morph, no node:fs — operates on a flat list of candidates each carrying
- * a composed `fullUrl` and an opaque `value`. Matching mirrors UIRouter's
- * literal-then-param preference: a literal segment-for-segment match wins over a
- * parameterised one, and ties at either tier collapse to an `ambiguous` result.
- */ /**
- * Collapses an empty pathname to `/` and strips a single trailing slash so
- * `/a/b/` and `/a/b` compare equal.
- *
- * @param pathname - The raw pathname to normalize.
- * @returns The normalized pathname.
- */ function normalizePathname(pathname) {
-    var result;
-    if (pathname.length === 0) {
-        result = '/';
-    } else if (pathname.length > 1 && pathname.endsWith('/')) {
-        result = pathname.slice(0, -1);
-    } else {
-        result = pathname;
+function detectCycleFor(treeNode, issues) {
+    var seen = new Set();
+    seen.add(treeNode.data.name);
+    var cursor = treeNode.parent;
+    while(cursor){
+        if (seen.has(cursor.data.name)) {
+            issues.push({
+                code: 'CYCLE_DETECTED',
+                severity: 'error',
+                message: "Cycle detected involving `".concat(treeNode.data.name, "` and `").concat(cursor.data.name, "`. Severing the parent link."),
+                file: treeNode.data.file,
+                line: treeNode.data.line,
+                stateName: treeNode.data.name
+            });
+            detachFromParent(treeNode);
+            return;
+        }
+        seen.add(cursor.data.name);
+        cursor = cursor.parent;
     }
-    return result;
-}
-/**
- * Splits a path into its non-empty segments (the leading slash is dropped).
- *
- * @param path - The path or URL pattern to split.
- * @returns The ordered segment list, empty for `/`.
- */ function splitSegments(path) {
-    var normalized = path.startsWith('/') ? path.slice(1) : path;
-    return normalized.length === 0 ? [] : normalized.split('/');
-}
-/**
- * Whether a composed URL contains at least one `:param` or `{param}` segment.
- *
- * @param path - The composed URL pattern.
- * @returns `true` when the pattern declares a parameter.
- */ function hasParamSegment(path) {
-    return path.includes(':') || path.includes('{');
 }
-/**
- * Attempts a segment-for-segment match of a route pattern against concrete
- * input segments. `:name` and `{name}` / `{name:type}` segments capture the
- * input value (URL-decoded); literal segments must match exactly.
- *
- * @param route - The route pattern's segments.
- * @param input - The concrete URL's segments.
- * @returns The captured params when every segment matches, else `undefined`.
- */ function tryMatchSegments(route, input) {
-    if (route.length !== input.length) {
-        return undefined;
+function detachFromParent(treeNode) {
+    if (!treeNode.parent) return;
+    var idx = treeNode.parent.children.indexOf(treeNode);
+    if (idx >= 0) {
+        treeNode.parent.children.splice(idx, 1);
     }
-    var params = {};
-    var result = params;
+    treeNode.parent = undefined;
+}
+// (4) Compose full URLs (parent walk; root url is not prefixed). UIRouter's
+// own logic is more nuanced (some states overwrite their parent's URL with
+// a leading `^`), but this gives a useful approximation for the common case.
+function composeFullUrls(byName) {
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
-        for(var _iterator = route.entries()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
-            var _step_value = _sliced_to_array$1(_step.value, 2), i = _step_value[0], r = _step_value[1];
-            var v = input[i];
-            if (r.startsWith(':')) {
-                var key = r.slice(1);
-                params[key] = decodeURIComponent(v);
-            } else if (r.startsWith('{') && r.endsWith('}')) {
-                var inner = r.slice(1, -1);
-                var colonIdx = inner.indexOf(':');
-                var key1 = colonIdx >= 0 ? inner.slice(0, colonIdx) : inner;
-                params[key1] = decodeURIComponent(v);
-            } else if (r !== v) {
-                result = undefined;
-                break;
-            }
+        for(var _iterator = byName.values()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var treeNode = _step.value;
+            treeNode.fullUrl = composeFullUrl(treeNode);
         }
     } catch (err) {
         _didIteratorError = true;
@@ -57835,31 +57815,16 @@ function _unsupported_iterable_to_array$2(o, minLen) {
             }
         }
     }
-    return result;
 }
-/**
- * Extracts param-name segments from a composed UIRouter URL. Recognises:
- * - `:name` (Express-style)
- * - `{name}` (UIRouter type-less)
- * - `{name:type}` and `{name:regex}` (UIRouter typed / regex)
- * Order is preserved; duplicates are de-duplicated by first occurrence.
- *
- * @param fullUrl - Composed URL (e.g. `/{orgId}/users/:userId`) or undefined.
- * @returns The param key list in declaration order, or an empty array.
- */ function extractUrlParamKeys(fullUrl) {
-    if (fullUrl === undefined || fullUrl.length === 0) {
-        return [];
-    }
-    var seen = new Set();
-    var keys = [];
+// (5) Identify roots
+function collectRoots(byName) {
+    var roots = [];
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
-        for(var _iterator = fullUrl.split('/')[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
-            var segment = _step.value;
-            var key = extractParamKeyFromSegment(segment);
-            if (key !== undefined && !seen.has(key)) {
-                seen.add(key);
-                keys.push(key);
+        for(var _iterator = byName.values()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var treeNode = _step.value;
+            if (!treeNode.parent) {
+                roots.push(treeNode);
             }
         }
     } catch (err) {
@@ -57876,64 +57841,15 @@ function _unsupported_iterable_to_array$2(o, minLen) {
             }
         }
     }
-    return keys;
-}
-function extractParamKeyFromSegment(segment) {
-    if (segment.startsWith(':')) {
-        var key = segment.slice(1);
-        return key.length > 0 ? key : undefined;
-    }
-    if (segment.startsWith('{') && segment.endsWith('}')) {
-        var inner = segment.slice(1, -1);
-        var colonIdx = inner.indexOf(':');
-        var rawKey = colonIdx >= 0 ? inner.slice(0, colonIdx) : inner;
-        var key1 = rawKey.trim();
-        return key1.length > 0 ? key1 : undefined;
-    }
-    return undefined;
-}
-/**
- * Matches a pathname against a flat candidate list, preferring a literal
- * (exact composed-URL) match over a parameterised one. A tie at either tier
- * collapses to `ambiguous`; otherwise the closest near-misses are scored and
- * returned in a `none` result.
- *
- * @param input - The candidate entries and the pathname to resolve.
- * @returns A discriminated match / ambiguous / none result.
- */ function matchUrlAgainstEntries(input) {
-    var pathname = normalizePathname(input.pathname);
-    var literal = matchLiteral(input.entries, pathname);
-    var result;
-    if (literal.length === 1) {
-        var _literal__fullUrl;
-        result = {
-            kind: 'match',
-            via: 'literal',
-            value: literal[0].value,
-            matchedFullUrl: normalizePathname((_literal__fullUrl = literal[0].fullUrl) !== null && _literal__fullUrl !== void 0 ? _literal__fullUrl : pathname),
-            params: {}
-        };
-    } else if (literal.length > 1) {
-        result = {
-            kind: 'ambiguous',
-            values: literal.map(function(e) {
-                return e.value;
-            })
-        };
-    } else {
-        result = matchParamOrNone(input.entries, pathname);
-    }
-    return result;
+    return roots;
 }
-function matchLiteral(entries, pathname) {
-    var out = [];
+// (6) Sort children deterministically by name
+function sortChildren(byName, roots) {
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
-        for(var _iterator = entries[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
-            var entry = _step.value;
-            if (entry.fullUrl !== undefined && normalizePathname(entry.fullUrl) === pathname) {
-                out.push(entry);
-            }
+        for(var _iterator = byName.values()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var treeNode = _step.value;
+            treeNode.children.sort(compareByName);
         }
     } catch (err) {
         _didIteratorError = true;
@@ -57949,24 +57865,135 @@ function matchLiteral(entries, pathname) {
             }
         }
     }
-    return out;
+    roots.sort(compareByName);
 }
-function matchParamOrNone(entries, pathname) {
-    var inputSegments = splitSegments(pathname);
-    var hits = [];
+// (7) Freeze: convert MutableTreeNode → RouteTreeNode (children: readonly).
+function freezeTree(roots) {
+    var frozen = new Map();
+    var freeze = function freeze1(mut) {
+        var existing = frozen.get(mut.data.name);
+        if (existing) return existing;
+        var placeholder = {
+            data: mut.data,
+            fullUrl: mut.fullUrl,
+            parent: undefined,
+            children: []
+        };
+        frozen.set(mut.data.name, placeholder);
+        placeholder.parent = mut.parent ? freeze(mut.parent) : undefined;
+        placeholder.children = mut.children.map(freeze);
+        return placeholder;
+    };
+    var frozenRoots = roots.map(freeze);
+    return {
+        frozen: frozen,
+        frozenRoots: frozenRoots
+    };
+}
+function resolveParentName(node, byName) {
+    if (node.explicitParent) {
+        return node.explicitParent;
+    }
+    var lookupName = node.name.endsWith('.**') ? node.name.slice(0, -3) : node.name;
+    var lastDot = lookupName.lastIndexOf('.');
+    if (lastDot < 0) {
+        return undefined;
+    }
+    var candidate = lookupName.slice(0, lastDot);
+    // Confirm the candidate exists; otherwise fall back to undefined so the
+    // orphan check fires.
+    if (byName.has(candidate)) {
+        return candidate;
+    }
+    // Even if the candidate doesn't exist, return it so the orphan logic can
+    // surface an informative message.
+    return candidate;
+}
+function composeFullUrl(node) {
+    var segments = [];
+    var cursor = node;
+    while(cursor){
+        if (cursor.data.url !== undefined) {
+            segments.unshift(cursor.data.url);
+        }
+        cursor = cursor.parent;
+    }
+    if (segments.length === 0) {
+        return undefined;
+    }
+    // Join segments and collapse double slashes (root url '/' followed by
+    // child '/foo' would otherwise yield '//foo').
+    var joined = segments.join('');
+    // Strip any UIRouter query/hash suffix (e.g. `/:schoolJob?slotIndex`) so the
+    // stored `fullUrl` is path-only — keeping build-time param extraction and the
+    // runtime pathname matcher in agreement.
+    var collapsed = stripUrlQueryAndHash(joined).replaceAll(/\/{2,}/g, '/');
+    return collapsed.length === 0 ? '/' : collapsed;
+}
+function compareByName(a, b) {
+    if (a.data.name < b.data.name) {
+        return -1;
+    }
+    if (a.data.name > b.data.name) {
+        return 1;
+    }
+    return 0;
+}
+
+/**
+ * Walks every supplied source through the extractor and emits a flat node and
+ * issue list, used when the caller has already gathered a complete glob/file
+ * set in memory.
+ *
+ * @param sources - The in-memory sources to extract from.
+ * @returns The merged extraction nodes, issues, and processed file count.
+ */ function resolveRouteSources(sources) {
+    var nodes = [];
+    var issues = [];
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
-        for(var _iterator = entries[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
-            var entry = _step.value;
-            if (entry.fullUrl === undefined || !hasParamSegment(entry.fullUrl)) {
-                continue;
+        for(var _iterator = sources[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var source = _step.value;
+            var extracted = extractFile(source);
+            var _iteratorNormalCompletion1 = true, _didIteratorError1 = false, _iteratorError1 = undefined;
+            try {
+                for(var _iterator1 = extracted.nodes[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true){
+                    var node = _step1.value;
+                    nodes.push(node);
+                }
+            } catch (err) {
+                _didIteratorError1 = true;
+                _iteratorError1 = err;
+            } finally{
+                try {
+                    if (!_iteratorNormalCompletion1 && _iterator1.return != null) {
+                        _iterator1.return();
+                    }
+                } finally{
+                    if (_didIteratorError1) {
+                        throw _iteratorError1;
+                    }
+                }
             }
-            var params = tryMatchSegments(splitSegments(entry.fullUrl), inputSegments);
-            if (params) {
-                hits.push({
-                    entry: entry,
-                    params: params
-                });
+            var _iteratorNormalCompletion2 = true, _didIteratorError2 = false, _iteratorError2 = undefined;
+            try {
+                for(var _iterator2 = extracted.issues[Symbol.iterator](), _step2; !(_iteratorNormalCompletion2 = (_step2 = _iterator2.next()).done); _iteratorNormalCompletion2 = true){
+                    var issue = _step2.value;
+                    issues.push(issue);
+                }
+            } catch (err) {
+                _didIteratorError2 = true;
+                _iteratorError2 = err;
+            } finally{
+                try {
+                    if (!_iteratorNormalCompletion2 && _iterator2.return != null) {
+                        _iterator2.return();
+                    }
+                } finally{
+                    if (_didIteratorError2) {
+                        throw _iteratorError2;
+                    }
+                }
             }
         }
     } catch (err) {
@@ -57983,66 +58010,28 @@ function matchParamOrNone(entries, pathname) {
             }
         }
     }
-    var result;
-    if (hits.length === 1) {
-        var _hits__entry_fullUrl;
-        result = {
-            kind: 'match',
-            via: 'param',
-            value: hits[0].entry.value,
-            matchedFullUrl: normalizePathname((_hits__entry_fullUrl = hits[0].entry.fullUrl) !== null && _hits__entry_fullUrl !== void 0 ? _hits__entry_fullUrl : pathname),
-            params: hits[0].params
-        };
-    } else if (hits.length > 1) {
-        result = {
-            kind: 'ambiguous',
-            values: hits.map(function(h) {
-                return h.entry.value;
-            })
-        };
-    } else {
-        result = {
-            kind: 'none',
-            candidates: scoreCandidates(entries, pathname)
-        };
-    }
+    var result = {
+        nodes: nodes,
+        issues: issues,
+        filesChecked: sources.length
+    };
     return result;
 }
 /**
- * Scores every candidate by shared leading segments (literal segment = 2,
- * param segment = 1, mismatch stops scoring) and returns the top 5 values.
+ * Returns the relative module specifiers imported by `source` — used to plan
+ * the next round of file reads in transitive walking. Specifiers are
+ * left untouched (no `.ts` resolution); the caller normalizes them.
  *
- * @param entries - The candidate entries to score.
- * @param pathname - The pathname being resolved.
- * @returns Up to five closest candidate values, best first.
- */ function scoreCandidates(entries, pathname) {
-    var segments = splitSegments(normalizePathname(pathname));
-    var scored = [];
+ * @param source - The in-memory source to inspect.
+ * @returns The relative specifiers in original-source order.
+ */ function computeRelativeSpecifiers(source) {
+    var extracted = extractFile(source);
+    var out = [];
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
-        for(var _iterator = entries[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
-            var entry = _step.value;
-            if (entry.fullUrl === undefined) {
-                continue;
-            }
-            var candidateSegments = splitSegments(entry.fullUrl);
-            var score = 0;
-            var maxIndex = Math.min(segments.length, candidateSegments.length);
-            for(var i = 0; i < maxIndex; i += 1){
-                if (segments[i] === candidateSegments[i]) {
-                    score += 2;
-                } else if (candidateSegments[i].startsWith(':') || candidateSegments[i].startsWith('{')) {
-                    score += 1;
-                } else {
-                    break;
-                }
-            }
-            if (score > 0) {
-                scored.push({
-                    value: entry.value,
-                    score: score
-                });
-            }
+        for(var _iterator = extracted.importedFromRelative[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+            var imp = _step.value;
+            out.push(imp.moduleSpecifier);
         }
     } catch (err) {
         _didIteratorError = true;
@@ -58058,12 +58047,26 @@ function matchParamOrNone(entries, pathname) {
             }
         }
     }
-    scored.sort(function(a, b) {
-        return b.score - a.score;
-    });
-    return scored.slice(0, 5).map(function(s) {
-        return s.value;
-    });
+    return out;
+}
+
+/**
+ * Pure tree-loading entry point. Resolves the supplied source list and builds
+ * the parent/child tree in one step so callers can stay thin.
+ *
+ * @param args - The in-memory sources to process.
+ * @returns The constructed route tree with extraction issues attached.
+ */ function loadRouteTree(args) {
+    var resolved = resolveRouteSources(args.sources);
+    var tree = buildRouteTree(resolved.nodes, resolved.issues);
+    var result = {
+        roots: tree.roots,
+        byName: tree.byName,
+        issues: tree.issues,
+        filesChecked: resolved.filesChecked,
+        nodeCount: tree.nodeCount
+    };
+    return result;
 }
 
 function _tagged_template_literal(strings, raw) {
@@ -58290,6 +58293,13 @@ function _unsupported_iterable_to_array$1(o, minLen) {
  *   promoted to `<collectionName>/<id>` at runtime via the model identity).
  * - `gb/:id/gbe/{authUid}` — alternating literal / placeholder segments (even
  *   count) → `kind: 'key'` (a full FirestoreModelKey for a subcollection model).
+ *   An odd (id) segment may also be a `{const:<id>}` token for a fixed/singleton
+ *   id (e.g. `wk/:uid/wkn/{const:0}`); it is normalized to the bare literal in
+ *   the parsed `keyTemplate` so the runtime emits it verbatim, while a forgotten
+ *   `:` (a bare `note`) still fails as malformed.
+ * - `{flatKey:<param>}` — single token → `kind: 'flatKey'`: the `<param>` URL
+ *   value IS a whole two-way-flat FirestoreModelKey (`r_<id>_cs_<id>_d_<id>`),
+ *   un-flattened at runtime. For pages that pack a full key into one URL segment.
  * - (absent, list tag) → `kind: 'list'`.
  *
  * This module is deliberately runtime-dependency-free (no ts-morph): the same
@@ -58300,6 +58310,14 @@ function _unsupported_iterable_to_array$1(o, minLen) {
  */ var MODEL_TYPE_RE = RegExp("^[a-zA-Z][a-zA-Z0-9]*$", "u");
 var LITERAL_SEGMENT_RE = RegExp("^[a-zA-Z0-9][a-zA-Z0-9_-]*$", "u");
 var AUTH_UID_PLACEHOLDER = '{authUid}';
+/**
+ * Matches a `{const:<id>}` fixed-id token (e.g. `{const:0}`), capturing the
+ * literal id. The id obeys the same shape as a literal collection segment.
+ */ var CONST_TOKEN_RE = RegExp("^\\{const:([a-zA-Z0-9][a-zA-Z0-9_-]*)\\}$", "u");
+/**
+ * Matches a `{flatKey:<param>}` token (e.g. `{flatKey:region}`), capturing the
+ * route param name whose URL value holds a whole two-way-flat FirestoreModelKey.
+ */ var FLAT_KEY_TOKEN_RE = RegExp("^\\{flatKey:([a-zA-Z_][a-zA-Z0-9_]*)\\}$", "u");
 /**
  * The bare `@dbxRouteModel` tag name (without the leading `@`).
  */ var ROUTE_MODEL_TAG = 'dbxRouteModel';
@@ -58379,7 +58397,7 @@ function parseModelTag(tokens, description) {
                 model: {
                     modelType: tokens[0],
                     kind: parsedKey.kind,
-                    keyTemplate: tokens[1],
+                    keyTemplate: parsedKey.keyTemplate,
                     description: description,
                     routeParams: parsedKey.routeParams
                 }
@@ -58414,17 +58432,29 @@ function parseKeyTemplate(keyTemplate) {
     return result;
 }
 function parseSingleSegmentKey(segment, keyTemplate) {
+    var flatKeyParam = flatKeyTokenParam(segment);
     var placeholder = placeholderParam(segment);
     var result;
-    if (placeholder === undefined) {
+    if (flatKeyParam !== undefined) {
+        // The whole key lives in one URL param; the runtime un-flattens it.
+        result = {
+            ok: true,
+            kind: 'flatKey',
+            keyTemplate: keyTemplate,
+            routeParams: [
+                flatKeyParam
+            ]
+        };
+    } else if (placeholder === undefined) {
         result = {
             ok: false,
-            message: "Single-segment key template `".concat(keyTemplate, "` must be a placeholder (`:param` or `").concat(AUTH_UID_PLACEHOLDER, "`).")
+            message: "Single-segment key template `".concat(keyTemplate, "` must be a placeholder (`:param` or `").concat(AUTH_UID_PLACEHOLDER, "`) or a flattened-key token (`{flatKey:<param>}`).")
         };
     } else {
         result = {
             ok: true,
             kind: 'id',
+            keyTemplate: keyTemplate,
             routeParams: placeholder.routeParam === undefined ? [] : [
                 placeholder.routeParam
             ]
@@ -58434,6 +58464,10 @@ function parseSingleSegmentKey(segment, keyTemplate) {
 }
 function parseAlternatingKey(segments, keyTemplate) {
     var routeParams = [];
+    // The normalized template substitutes any `{const:<id>}` token back to its
+    // bare literal so the runtime `resolveFullKey` (which emits non-placeholder
+    // segments verbatim) round-trips without needing to understand the token.
+    var normalizedSegments = [];
     var message;
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
     try {
@@ -58444,14 +58478,20 @@ function parseAlternatingKey(segments, keyTemplate) {
                     message = "Key template `".concat(keyTemplate, "` segment `").concat(segment, "` must be a literal collection name.");
                     break;
                 }
+                normalizedSegments.push(segment);
             } else {
                 var placeholder = placeholderParam(segment);
-                if (placeholder === undefined) {
-                    message = "Key template `".concat(keyTemplate, "` segment `").concat(segment, "` must be a placeholder (`:param` or `").concat(AUTH_UID_PLACEHOLDER, "`).");
+                var constId = constTokenId(segment);
+                if (placeholder !== undefined) {
+                    if (placeholder.routeParam !== undefined) {
+                        routeParams.push(placeholder.routeParam);
+                    }
+                    normalizedSegments.push(segment);
+                } else if (constId === undefined) {
+                    message = "Key template `".concat(keyTemplate, "` segment `").concat(segment, "` must be a placeholder (`:param` or `").concat(AUTH_UID_PLACEHOLDER, "`) or a fixed id (`{const:<id>}`).");
                     break;
-                }
-                if (placeholder.routeParam !== undefined) {
-                    routeParams.push(placeholder.routeParam);
+                } else {
+                    normalizedSegments.push(constId);
                 }
             }
         }
@@ -58472,6 +58512,7 @@ function parseAlternatingKey(segments, keyTemplate) {
     return message === undefined ? {
         ok: true,
         kind: 'key',
+        keyTemplate: normalizedSegments.join('/'),
         routeParams: routeParams
     } : {
         ok: false,
@@ -58501,6 +58542,28 @@ function parseAlternatingKey(segments, keyTemplate) {
     }
     return result;
 }
+/**
+ * Extracts the literal id from a `{const:<id>}` fixed-id token, used for a
+ * fixed/singleton subcollection id at an odd key-template position. Returns
+ * `undefined` for any non-`{const:…}` segment.
+ *
+ * @param segment - The single key-template segment to classify.
+ * @returns The captured literal id, or `undefined` when not a const token.
+ */ function constTokenId(segment) {
+    var match = CONST_TOKEN_RE.exec(segment);
+    return match === null ? undefined : match[1];
+}
+/**
+ * Extracts the route param name from a `{flatKey:<param>}` token, whose URL
+ * value is a whole two-way-flat FirestoreModelKey un-flattened at runtime.
+ * Returns `undefined` for any non-`{flatKey:…}` segment.
+ *
+ * @param segment - The single key-template segment to classify.
+ * @returns The captured route param name, or `undefined` when not a flatKey token.
+ */ function flatKeyTokenParam(segment) {
+    var match = FLAT_KEY_TOKEN_RE.exec(segment);
+    return match === null ? undefined : match[1];
+}
 
 // MARK: Component extraction
 /**
@@ -58643,7 +58706,7 @@ function _unsupported_iterable_to_array(o, minLen) {
  * Version stamp embedded in `route.manifest.json`. Runtime loaders refuse
  * manifests whose `version` does not match. Mirror in firebase-server/mcp's
  * `ROUTE_MANIFEST_VERSION` — bump both together.
- */ var ROUTE_MANIFEST_VERSION = 1;
+ */ var ROUTE_MANIFEST_VERSION = 2;
 /**
  * Builds the route manifest from a set of app sources.
  *
@@ -60216,6 +60279,7 @@ exports.setCliTimeoutMs = setCliTimeoutMs;
 exports.setCliVerbose = setCliVerbose;
 exports.splitListTagText = splitListTagText$1;
 exports.splitSegments = splitSegments;
+exports.stripUrlQueryAndHash = stripUrlQueryAndHash;
 exports.toActionEntryInfo = toActionEntryInfo;
 exports.toFilterEntryInfo = toFilterEntryInfo;
 exports.toFormFieldInfo = toFormFieldInfo;