@needle-tools/addressing 0.3.1 → 0.3.2

package/dist/resolve.d.ts

@@ -0,0 +1,30 @@
+import { type GraphNode, type NeedleAddress } from "./address.js";
+import { type GltfJson } from "./gltf.js";
+export type GltfResolveResult = {
+    type: string;
+    index: number;
+    element: Record<string, unknown>;
+};
+/**
+ * Resolve an address inside glTF JSON. Tries id → anchor → namePath (nodes), in that
+ * order; returns null when nothing matches exactly (reconciliation is a separate,
+ * explicit step — resolution never guesses).
+ */
+export declare function resolveInGltf(address: NeedleAddress, json: GltfJson): GltfResolveResult | null;
+/**
+ * Resolve an address inside a live scene graph (duck-typed — any three.js).
+ * Same order as glTF resolution: id → anchor → namePath.
+ */
+export declare function resolveInGraph(address: NeedleAddress, root: GraphNode): GraphNode | null;
+export type ReconcileCandidate = {
+    object: GraphNode;
+    /** 0..1 — heuristic, for ranking and thresholds; 1.0 is reserved for exact resolution */
+    confidence: number;
+    reasons: string[];
+};
+/**
+ * When exact resolution fails (the asset changed), propose candidates instead of
+ * guessing: nodes matching the address's name, ranked by how much of the recorded
+ * namePath still matches. Callers decide thresholds and whether to re-anchor.
+ */
+export declare function reconcileInGraph(address: NeedleAddress, root: GraphNode): ReconcileCandidate[];

package/dist/resolve.js

@@ -0,0 +1,168 @@
+import { parseAnchorValue } from "./anchor.js";
+import { collectionKeyForType } from "./address.js";
+import { NEEDLE_ID_KEY, STAMPED_COLLECTIONS } from "./gltf.js";
+/**
+ * Resolve an address inside glTF JSON. Tries id → anchor → namePath (nodes), in that
+ * order; returns null when nothing matches exactly (reconciliation is a separate,
+ * explicit step — resolution never guesses).
+ */
+export function resolveInGltf(address, json) {
+    const searched = address.type
+        ? [[address.type, collectionKeyForType(address.type)]]
+        : [...STAMPED_COLLECTIONS];
+    if (address.id) {
+        for (const [type, key] of searched) {
+            const found = findInCollection(json, key, el => el.extras?.[NEEDLE_ID_KEY] === address.id);
+            if (found)
+                return { type, index: found.index, element: found.element };
+        }
+    }
+    if (address.anchor) {
+        for (const [type, key] of searched) {
+            const found = findInCollection(json, key, el => parseAnchorValue(el.name) === address.anchor);
+            if (found)
+                return { type, index: found.index, element: found.element };
+        }
+    }
+    if (address.namePath?.length && (!address.type || address.type === "node")) {
+        const index = walkGltfNamePath(json, address.namePath);
+        if (index !== null) {
+            const nodes = json["nodes"];
+            return { type: "node", index, element: nodes[index] };
+        }
+    }
+    return null;
+}
+/**
+ * Resolve an address inside a live scene graph (duck-typed — any three.js).
+ * Same order as glTF resolution: id → anchor → namePath.
+ */
+export function resolveInGraph(address, root) {
+    if (address.id) {
+        const byId = findInGraph(root, n => n.userData?.[NEEDLE_ID_KEY] === address.id);
+        if (byId)
+            return byId;
+    }
+    if (address.anchor) {
+        const byAnchor = findInGraph(root, n => parseAnchorValue(n.name) === address.anchor);
+        if (byAnchor)
+            return byAnchor;
+    }
+    if (address.namePath?.length) {
+        let current = root;
+        for (const segment of address.namePath) {
+            current = current.children?.find(c => (c.name ?? "") === segment) ?? null;
+            if (!current)
+                break;
+        }
+        if (current && current !== root)
+            return current;
+    }
+    return null;
+}
+/**
+ * When exact resolution fails (the asset changed), propose candidates instead of
+ * guessing: nodes matching the address's name, ranked by how much of the recorded
+ * namePath still matches. Callers decide thresholds and whether to re-anchor.
+ */
+export function reconcileInGraph(address, root) {
+    if (!address.name && !address.namePath?.length)
+        return [];
+    const targetName = address.name ?? address.namePath[address.namePath.length - 1];
+    const candidates = [];
+    collectDescendants(root, (node, namePath) => {
+        if ((node.name ?? "") !== targetName)
+            return;
+        const reasons = [`name matches "${targetName}"`];
+        let confidence = 0.5;
+        if (address.namePath?.length) {
+            const similarity = pathSuffixSimilarity(address.namePath, namePath);
+            confidence += 0.4 * similarity;
+            if (similarity > 0)
+                reasons.push(`path suffix similarity ${(similarity * 100).toFixed(0)}%`);
+        }
+        candidates.push({ object: node, confidence, reasons });
+    });
+    if (candidates.length === 1) {
+        candidates[0].confidence = Math.min(0.95, candidates[0].confidence + 0.1);
+        candidates[0].reasons.push("only candidate with this name");
+    }
+    return candidates.sort((a, b) => b.confidence - a.confidence);
+}
+function findInCollection(json, key, predicate) {
+    const collection = json[key];
+    if (!Array.isArray(collection))
+        return null;
+    for (let i = 0; i < collection.length; i++) {
+        const element = collection[i];
+        if (element != null && typeof element === "object" && predicate(element)) {
+            return { index: i, element };
+        }
+    }
+    return null;
+}
+function walkGltfNamePath(json, namePath) {
+    const nodes = json["nodes"];
+    const scenes = json["scenes"];
+    if (!Array.isArray(nodes) || !Array.isArray(scenes))
+        return null;
+    // roots: the union of all scenes' root nodes
+    let candidates = scenes.flatMap(s => (Array.isArray(s?.nodes) ? s.nodes : []));
+    let match = null;
+    for (const segment of namePath) {
+        match = candidates.find(i => ((nodes[i]?.name ?? "") === segment)) ?? null;
+        if (match === null)
+            return null;
+        const children = nodes[match]?.children;
+        candidates = Array.isArray(children) ? children : [];
+    }
+    return match;
+}
+function findInGraph(root, predicate, visited = new Set()) {
+    if (visited.has(root))
+        return null;
+    visited.add(root);
+    if (predicate(root))
+        return root;
+    if (!root.children)
+        return null;
+    for (let i = 0; i < root.children.length; i++) {
+        const child = root.children[i];
+        if (child == null)
+            continue;
+        const found = findInGraph(child, predicate, visited);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/** visit every descendant of root with its root-exclusive name path (including own name) */
+function collectDescendants(root, visit) {
+    const visited = new Set();
+    const walk = (node, namePath) => {
+        if (visited.has(node))
+            return;
+        visited.add(node);
+        if (node !== root)
+            visit(node, namePath);
+        if (!node.children)
+            return;
+        for (let i = 0; i < node.children.length; i++) {
+            const child = node.children[i];
+            if (child == null)
+                continue;
+            walk(child, [...namePath, child.name ?? ""]);
+        }
+    };
+    walk(root, []);
+}
+/** how much of the expected path's tail matches the actual path's tail (0..1) */
+function pathSuffixSimilarity(expected, actual) {
+    let shared = 0;
+    while (shared < expected.length &&
+        shared < actual.length &&
+        expected[expected.length - 1 - shared] === actual[actual.length - 1 - shared]) {
+        shared++;
+    }
+    return shared / Math.max(expected.length, actual.length);
+}

package/dist/uuid.d.ts

@@ -0,0 +1,12 @@
+/** RFC 4122 URL namespace — the namespace needle-cloud's `ensureUUID` uses (`uuidv5.URL`). */
+export declare const UUID_NAMESPACE_URL = "6ba7b811-9dad-11d1-80b4-00c04fd430c8";
+/**
+ * RFC 4122 version-5 (SHA-1, name-based) UUID. Byte-identical to the `uuid` npm
+ * package's `v5(name, namespace)`.
+ */
+export declare function uuidv5(name: string, namespace?: string): string;
+/**
+ * Random UUID for content that has no source file to be deterministic against
+ * (scratch content created in an editor). Uses the platform's crypto when available.
+ */
+export declare function randomUuid(): string;

package/dist/uuid.js

@@ -0,0 +1,49 @@
+import { sha1, toHex } from "./hash.js";
+/** RFC 4122 URL namespace — the namespace needle-cloud's `ensureUUID` uses (`uuidv5.URL`). */
+export const UUID_NAMESPACE_URL = "6ba7b811-9dad-11d1-80b4-00c04fd430c8";
+/**
+ * RFC 4122 version-5 (SHA-1, name-based) UUID. Byte-identical to the `uuid` npm
+ * package's `v5(name, namespace)`.
+ */
+export function uuidv5(name, namespace = UUID_NAMESPACE_URL) {
+    const ns = parseUuidBytes(namespace);
+    const nameBytes = new TextEncoder().encode(name);
+    const input = new Uint8Array(ns.length + nameBytes.length);
+    input.set(ns);
+    input.set(nameBytes, ns.length);
+    const hash = sha1(input).slice(0, 16);
+    hash[6] = (hash[6] & 0x0f) | 0x50; // version 5
+    hash[8] = (hash[8] & 0x3f) | 0x80; // RFC 4122 variant
+    return formatUuid(hash);
+}
+/**
+ * Random UUID for content that has no source file to be deterministic against
+ * (scratch content created in an editor). Uses the platform's crypto when available.
+ */
+export function randomUuid() {
+    const cryptoObj = globalThis.crypto;
+    if (cryptoObj?.randomUUID)
+        return cryptoObj.randomUUID();
+    const bytes = new Uint8Array(16);
+    if (cryptoObj?.getRandomValues)
+        cryptoObj.getRandomValues(bytes);
+    else
+        for (let i = 0; i < 16; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    return formatUuid(bytes);
+}
+function parseUuidBytes(uuid) {
+    const hex = uuid.replace(/-/g, "");
+    if (hex.length !== 32)
+        throw new Error(`Invalid UUID: ${uuid}`);
+    const bytes = new Uint8Array(16);
+    for (let i = 0; i < 16; i++)
+        bytes[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16);
+    return bytes;
+}
+function formatUuid(bytes) {
+    const hex = toHex(bytes);
+    return `${hex.substring(0, 8)}-${hex.substring(8, 12)}-${hex.substring(12, 16)}-${hex.substring(16, 20)}-${hex.substring(20)}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@needle-tools/addressing",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Persistent addressing for Needle assets: deterministic needle-id computation, #needle anchors, and address resolution over glTF JSON and live scene graphs.",
   "type": "module",
   "main": "./src/index.ts",
@@ -8,16 +8,19 @@
   "exports": {
     ".": {
       "types": "./src/index.ts",
+      "node": "./dist/index.js",
       "default": "./src/index.ts"
     }
   },
   "files": [
+    "dist",
     "src",
     "Readme.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "vitest run"
+    "test": "vitest run",
+    "prepack": "npm run build"
   },
   "author": {
     "name": "Needle",

package/src/address.ts

@@ -1,106 +1,106 @@
-import { parseAnchorValue } from "./anchor.js";
-import { getElementId, NEEDLE_ID_KEY, type GltfJson, type StampedElementType } from "./gltf.js";
-
-/**
- * A persistent pointer to an element inside an asset — the "fat address": every
- * fallback the resolver may need is captured at CREATION time, while the target is
- * known, instead of being reconstructed later.
- *
- * Resolution order: `id` (exact) → `anchor` (survives asset updates) → `namePath`
- * (best-effort) → reconciliation (candidates + confidence, never a silent guess).
- */
-export type NeedleAddress = {
-    /** the element's needle-id (deterministic for file-backed content, random for scratch) */
-    id?: string;
-    /** `#needle` anchor value, when the target's name carries one */
-    anchor?: string;
-    /** element type (`node`, `material`, …) — narrows resolution and validates matches */
-    type?: StampedElementType | (string & {});
-    /** the target's name at address-creation time */
-    name?: string;
-    /** node names from the asset root (exclusive) down to the target (inclusive); nodes only */
-    namePath?: string[];
-};
-
-/** Structural (duck-typed) view of a live scene-graph node — works with any three.js. */
-export type GraphNode = {
-    name?: string;
-    children?: readonly GraphNode[];
-    userData?: Record<string, unknown>;
-};
-
-/** Build an address for a glTF root-collection element. `namePath` only applies to nodes. */
-export function createGltfElementAddress(json: GltfJson, type: StampedElementType | string, index: number): NeedleAddress | null {
-    const collection = json[collectionKeyForType(type)];
-    if (!Array.isArray(collection)) return null;
-    const element = collection[index];
-    if (element == null || typeof element !== "object") return null;
-
-    const name = typeof element.name === "string" ? element.name : undefined;
-    const address: NeedleAddress = { type };
-    const id = getElementId(element);
-    if (id) address.id = id;
-    const anchor = parseAnchorValue(name);
-    if (anchor) address.anchor = anchor;
-    if (name !== undefined) address.name = name;
-    if (type === "node") {
-        const path = gltfNodeNamePath(json, index);
-        if (path) address.namePath = path;
-    }
-    return address;
-}
-
-/** Build an address for a live scene-graph object under `root`. */
-export function createObjectAddress(root: GraphNode, target: GraphNode): NeedleAddress | null {
-    const path = findPath(root, target);
-    if (!path) return null;
-
-    const address: NeedleAddress = { type: "node" };
-    const id = target.userData?.[NEEDLE_ID_KEY];
-    if (typeof id === "string") address.id = id;
-    const anchor = parseAnchorValue(target.name);
-    if (anchor) address.anchor = anchor;
-    if (typeof target.name === "string") address.name = target.name;
-    address.namePath = path.map(n => n.name ?? "");
-    return address;
-}
-
-export function collectionKeyForType(type: string): string {
-    // glTF collection keys are the pluralized type names; only "mesh" is irregular
-    return type === "mesh" ? "meshes" : `${type}s`;
-}
-
-/** names from root (exclusive) to the node at `nodeIndex` (inclusive), via the scene tree */
-function gltfNodeNamePath(json: GltfJson, nodeIndex: number): string[] | null {
-    const nodes = json["nodes"];
-    if (!Array.isArray(nodes)) return null;
-    const parents = new Map<number, number>();
-    for (let i = 0; i < nodes.length; i++) {
-        const children = nodes[i]?.children;
-        if (Array.isArray(children)) for (const c of children) parents.set(c, i);
-    }
-    const path: string[] = [];
-    let current: number | undefined = nodeIndex;
-    const seen = new Set<number>();
-    while (current !== undefined) {
-        if (seen.has(current)) return null; // malformed (cyclic) input
-        seen.add(current);
-        path.unshift(typeof nodes[current]?.name === "string" ? nodes[current].name : "");
-        current = parents.get(current);
-    }
-    return path;
-}
-
-/** path from root (exclusive) to target (inclusive), or null if target is not under root */
-export function findPath(root: GraphNode, target: GraphNode): GraphNode[] | null {
-    if (root === target) return [];
-    const children = root.children;
-    if (!children) return null;
-    for (let i = 0; i < children.length; i++) {
-        const child = children[i];
-        if (child == null) continue;
-        const sub = findPath(child, target);
-        if (sub) return [child, ...sub];
-    }
-    return null;
-}
+import { parseAnchorValue } from "./anchor.js";
+import { getElementId, NEEDLE_ID_KEY, type GltfJson, type StampedElementType } from "./gltf.js";
+
+/**
+ * A persistent pointer to an element inside an asset — the "fat address": every
+ * fallback the resolver may need is captured at CREATION time, while the target is
+ * known, instead of being reconstructed later.
+ *
+ * Resolution order: `id` (exact) → `anchor` (survives asset updates) → `namePath`
+ * (best-effort) → reconciliation (candidates + confidence, never a silent guess).
+ */
+export type NeedleAddress = {
+    /** the element's needle-id (deterministic for file-backed content, random for scratch) */
+    id?: string;
+    /** `#needle` anchor value, when the target's name carries one */
+    anchor?: string;
+    /** element type (`node`, `material`, …) — narrows resolution and validates matches */
+    type?: StampedElementType | (string & {});
+    /** the target's name at address-creation time */
+    name?: string;
+    /** node names from the asset root (exclusive) down to the target (inclusive); nodes only */
+    namePath?: string[];
+};
+
+/** Structural (duck-typed) view of a live scene-graph node — works with any three.js. */
+export type GraphNode = {
+    name?: string;
+    children?: readonly GraphNode[];
+    userData?: Record<string, unknown>;
+};
+
+/** Build an address for a glTF root-collection element. `namePath` only applies to nodes. */
+export function createGltfElementAddress(json: GltfJson, type: StampedElementType | string, index: number): NeedleAddress | null {
+    const collection = json[collectionKeyForType(type)];
+    if (!Array.isArray(collection)) return null;
+    const element = collection[index];
+    if (element == null || typeof element !== "object") return null;
+
+    const name = typeof element.name === "string" ? element.name : undefined;
+    const address: NeedleAddress = { type };
+    const id = getElementId(element);
+    if (id) address.id = id;
+    const anchor = parseAnchorValue(name);
+    if (anchor) address.anchor = anchor;
+    if (name !== undefined) address.name = name;
+    if (type === "node") {
+        const path = gltfNodeNamePath(json, index);
+        if (path) address.namePath = path;
+    }
+    return address;
+}
+
+/** Build an address for a live scene-graph object under `root`. */
+export function createObjectAddress(root: GraphNode, target: GraphNode): NeedleAddress | null {
+    const path = findPath(root, target);
+    if (!path) return null;
+
+    const address: NeedleAddress = { type: "node" };
+    const id = target.userData?.[NEEDLE_ID_KEY];
+    if (typeof id === "string") address.id = id;
+    const anchor = parseAnchorValue(target.name);
+    if (anchor) address.anchor = anchor;
+    if (typeof target.name === "string") address.name = target.name;
+    address.namePath = path.map(n => n.name ?? "");
+    return address;
+}
+
+export function collectionKeyForType(type: string): string {
+    // glTF collection keys are the pluralized type names; only "mesh" is irregular
+    return type === "mesh" ? "meshes" : `${type}s`;
+}
+
+/** names from root (exclusive) to the node at `nodeIndex` (inclusive), via the scene tree */
+function gltfNodeNamePath(json: GltfJson, nodeIndex: number): string[] | null {
+    const nodes = json["nodes"];
+    if (!Array.isArray(nodes)) return null;
+    const parents = new Map<number, number>();
+    for (let i = 0; i < nodes.length; i++) {
+        const children = nodes[i]?.children;
+        if (Array.isArray(children)) for (const c of children) parents.set(c, i);
+    }
+    const path: string[] = [];
+    let current: number | undefined = nodeIndex;
+    const seen = new Set<number>();
+    while (current !== undefined) {
+        if (seen.has(current)) return null; // malformed (cyclic) input
+        seen.add(current);
+        path.unshift(typeof nodes[current]?.name === "string" ? nodes[current].name : "");
+        current = parents.get(current);
+    }
+    return path;
+}
+
+/** path from root (exclusive) to target (inclusive), or null if target is not under root */
+export function findPath(root: GraphNode, target: GraphNode): GraphNode[] | null {
+    if (root === target) return [];
+    const children = root.children;
+    if (!children) return null;
+    for (let i = 0; i < children.length; i++) {
+        const child = children[i];
+        if (child == null) continue;
+        const sub = findPath(child, target);
+        if (sub) return [child, ...sub];
+    }
+    return null;
+}

package/src/anchor.ts

@@ -1,56 +1,68 @@
-/**
- * The name-anchor scheme: an element named `Door #needle` derives its deterministic id
- * from the text before the marker instead of (name, index, file hash) — so the id
- * survives content changes and asset re-uploads as long as the name stays.
- *
- * CONTRACT NOTE — the marker set is part of the id contract. Markers may be ADDED (new
- * names start anchoring), but never removed or re-prioritized, and every WRITER of ids
- * (this package's consumers: cloud upload, editors, CLI) must agree on the set before a
- * new marker ships — a writer that anchors on a marker another writer doesn't know mints
- * DIFFERENT ids for the same file. The anchored id only hashes the VALUE (not the
- * marker), so all markers are aliases into the same id space.
- */
-
-/** the original marker — kept as a named export for existing consumers */
-export const ANCHOR_MARKER = "#needle";
-
-/**
- * All recognized markers, matched longest-first so overlapping suffixes resolve
- * deterministically. Currently one entry; see the contract note before adding more.
- */
-export const ANCHOR_MARKERS: readonly string[] = [ANCHOR_MARKER];
-
-export type ParsedAnchor = {
-    /** the marker that matched (one of {@link ANCHOR_MARKERS}) */
-    marker: string;
-    /** the anchor value — the deterministic-id input */
-    value: string;
-};
-
-/**
- * Parse an element name against all recognized markers (case-insensitive suffix match).
- * Returns null when no marker matches or the anchor value is empty.
- */
-export function parseAnchor(rawName: string | null | undefined): ParsedAnchor | null {
-    if (rawName == null) return null;
-    const trimmed = rawName.trim();
-    const lower = trimmed.toLowerCase();
-    for (const marker of byLengthDescending(ANCHOR_MARKERS)) {
-        if (!lower.endsWith(marker)) continue;
-        const value = trimmed.substring(0, trimmed.length - marker.length).trim();
-        return value.length > 0 ? { marker, value } : null;
-    }
-    return null;
-}
-
-/**
- * Extract the anchor value from an element name, or null when the name carries no anchor.
- * Convenience over {@link parseAnchor} for callers that only need the id input.
- */
-export function parseAnchorValue(rawName: string | null | undefined): string | null {
-    return parseAnchor(rawName)?.value ?? null;
-}
-
-function byLengthDescending(markers: readonly string[]): readonly string[] {
-    return markers.length > 1 ? [...markers].sort((a, b) => b.length - a.length) : markers;
-}
+/**
+ * The name-anchor scheme: an element named `Door #needle` derives its deterministic id
+ * from the text before the marker instead of (name, index, file hash) — so the id
+ * survives content changes and asset re-uploads as long as the name stays.
+ *
+ * CONTRACT NOTE — the marker set is part of the id contract. Markers may be ADDED (new
+ * names start anchoring), but never removed or re-prioritized, and every WRITER of ids
+ * (this package's consumers: cloud upload, editors, CLI) must agree on the set before a
+ * new marker ships — a writer that anchors on a marker another writer doesn't know mints
+ * DIFFERENT ids for the same file. The anchored id only hashes the VALUE (not the
+ * marker), so all markers are aliases into the same id space.
+ */
+
+/** the original marker — kept as a named export for existing consumers */
+export const ANCHOR_MARKER = "#needle";
+
+/**
+ * All recognized markers, matched longest-first so overlapping suffixes resolve
+ * deterministically. Currently one entry; see the contract note before adding more.
+ */
+export const ANCHOR_MARKERS: readonly string[] = [ANCHOR_MARKER];
+
+export type ParsedAnchor = {
+    /** the marker that matched (one of {@link ANCHOR_MARKERS}) */
+    marker: string;
+    /** the anchor value — the deterministic-id input */
+    value: string;
+};
+
+/**
+ * Parse an element name against all recognized markers (case-insensitive suffix match).
+ * Returns null when no marker matches or the anchor value is empty.
+ */
+export function parseAnchor(rawName: string | null | undefined): ParsedAnchor | null {
+    if (rawName == null) return null;
+    const trimmed = rawName.trim();
+    const lower = trimmed.toLowerCase();
+    for (const marker of byLengthDescending(ANCHOR_MARKERS)) {
+        if (!lower.endsWith(marker)) continue;
+        const value = normalizeAnchorValue(trimmed.substring(0, trimmed.length - marker.length));
+        return value.length > 0 ? { marker, value } : null;
+    }
+    return null;
+}
+
+/**
+ * Anchor values treat SPACES and UNDERSCORES as the same character (runs collapse to
+ * one space): three's GLTFLoader sanitizes node names on load (whitespace becomes
+ * "_"), so "Door Frame #needle" appears live as "Door_Frame_#needle" — without
+ * normalization the stamped anchor and the live anchor would never match. Applied at
+ * PARSE time, so id computation and resolution agree from one change point. Accepted
+ * trade: names differing only by space-vs-underscore share one anchor.
+ */
+function normalizeAnchorValue(value: string): string {
+    return value.replace(/[\s_]+/g, " ").trim();
+}
+
+/**
+ * Extract the anchor value from an element name, or null when the name carries no anchor.
+ * Convenience over {@link parseAnchor} for callers that only need the id input.
+ */
+export function parseAnchorValue(rawName: string | null | undefined): string | null {
+    return parseAnchor(rawName)?.value ?? null;
+}
+
+function byLengthDescending(markers: readonly string[]): readonly string[] {
+    return markers.length > 1 ? [...markers].sort((a, b) => b.length - a.length) : markers;
+}