@needle-tools/addressing 0.3.2 → 0.3.3

package/Readme.md

@@ -1,70 +1,70 @@
-# @needle-tools/addressing
-
-Persistent addressing for glTF assets and three.js scene graphs: deterministic
-`needle-id` computation, the `#needle` name-anchor scheme, and address resolution.
-
-Zero runtime dependencies, no three.js import (scene graphs are accessed structurally),
-usable in browsers, node, and workers.
-
-## Ids
-
-Every glTF root-collection element (nodes, scenes, animations, cameras, materials,
-meshes, skins, textures, images, samplers) can carry a UUID in `extras["needle-id"]`:
-
-- **Anchored** — the element name ends with `#needle` (case-insensitive): the id derives
-  only from the text before the marker → it **survives any content change** as long as
-  the name stays. Spaces and underscores in the value are treated as equal (loaders
-  sanitize node names), so `Door Frame #needle` and `Door_Frame_#needle` share one id.
-- **Unanchored**: the id derives from the element's type, name, and its occurrence among
-  same-named elements → uniquely named elements keep their ids across reorders and
-  content updates; duplicates disambiguate by position within their name group; unnamed
-  elements are positional.
-
-`ensureIds(gltfJson)` stamps a parsed glTF idempotently — existing ids are never
-overwritten, and any tool stamping the same element mints the same id.
-
-`ensureIds(gltfJson, { baseHash })` optionally salts unanchored ids with a caller-supplied
-identity (e.g. a stable asset id), scoping them to that identity.
-
-## Addresses
-
-An address captures every fallback at creation time, while the target is known —
-`{ id, anchor?, type?, name?, namePath? }`. Resolution order is strict:
-
-1. `id` — exact match (`extras` in glTF JSON, `userData` in live scene graphs)
-2. `anchor` — survives asset updates
-3. `namePath` — best-effort structural match
-4. **reconciliation** — never automatic: `reconcileInGraph` returns ranked candidates
-   with confidence + reasons; the caller decides thresholds and whether to re-anchor.
-
-## API
-
-```ts
-import {
-    ensureIds, computeElementId, computeFileHash,         // write side
-    createGltfElementAddress, createObjectAddress,        // address records
-    resolveInGltf, resolveInGraph, reconcileInGraph,      // resolve side
-    parseAnchorValue, randomUuid, NEEDLE_ID_KEY,
-} from "@needle-tools/addressing";
-
-// stamp a parsed glTF (idempotent, never overwrites existing ids)
-const { fileHash, assigned } = ensureIds(gltfJson);
-
-// capture an address while the target is known
-const address = createObjectAddress(sceneRoot, targetObject);
-
-// later / elsewhere: resolve — or reconcile when the asset changed
-const hit = resolveInGraph(address, sceneRoot);
-const candidates = hit ? [] : reconcileInGraph(address, sceneRoot);
-```
-
-Out of scope by design: GLB container parsing (this package takes parsed JSON), file
-I/O, and any composition/override semantics.
-
-## Development
-
-```
-npm install
-npm test        # vitest — includes golden-fixture id tests
-npm run build   # tsc → dist/
-```
+# @needle-tools/addressing
+
+Persistent addressing for glTF assets and three.js scene graphs: deterministic
+`needle-id` computation, the `#needle` name-anchor scheme, and address resolution.
+
+Zero runtime dependencies, no three.js import (scene graphs are accessed structurally),
+usable in browsers, node, and workers.
+
+## Ids
+
+Every glTF root-collection element (nodes, scenes, animations, cameras, materials,
+meshes, skins, textures, images, samplers) can carry a UUID in `extras["needle-id"]`:
+
+- **Anchored** — the element name ends with `#needle` (case-insensitive): the id derives
+  only from the text before the marker → it **survives any content change** as long as
+  the name stays. Spaces and underscores in the value are treated as equal (loaders
+  sanitize node names), so `Door Frame #needle` and `Door_Frame_#needle` share one id.
+- **Unanchored**: the id derives from the element's type, name, and its occurrence among
+  same-named elements → uniquely named elements keep their ids across reorders and
+  content updates; duplicates disambiguate by position within their name group; unnamed
+  elements are positional.
+
+`ensureIds(gltfJson)` stamps a parsed glTF idempotently — existing ids are never
+overwritten, and any tool stamping the same element mints the same id.
+
+`ensureIds(gltfJson, { baseHash })` optionally salts unanchored ids with a caller-supplied
+identity (e.g. a stable asset id), scoping them to that identity.
+
+## Addresses
+
+An address captures every fallback at creation time, while the target is known —
+`{ id, anchor?, type?, name?, namePath? }`. Resolution order is strict:
+
+1. `id` — exact match (`extras` in glTF JSON, `userData` in live scene graphs)
+2. `anchor` — survives asset updates
+3. `namePath` — best-effort structural match
+4. **reconciliation** — never automatic: `reconcileInGraph` returns ranked candidates
+   with confidence + reasons; the caller decides thresholds and whether to re-anchor.
+
+## API
+
+```ts
+import {
+    ensureIds, computeElementId, computeFileHash,         // write side
+    createGltfElementAddress, createObjectAddress,        // address records
+    resolveInGltf, resolveInGraph, reconcileInGraph,      // resolve side
+    parseAnchorValue, randomUuid, NEEDLE_ID_KEY,
+} from "@needle-tools/addressing";
+
+// stamp a parsed glTF (idempotent, never overwrites existing ids)
+const { fileHash, assigned } = ensureIds(gltfJson);
+
+// capture an address while the target is known
+const address = createObjectAddress(sceneRoot, targetObject);
+
+// later / elsewhere: resolve — or reconcile when the asset changed
+const hit = resolveInGraph(address, sceneRoot);
+const candidates = hit ? [] : reconcileInGraph(address, sceneRoot);
+```
+
+Out of scope by design: GLB container parsing (this package takes parsed JSON), file
+I/O, and any composition/override semantics.
+
+## Development
+
+```
+npm install
+npm test        # vitest — includes golden-fixture id tests
+npm run build   # tsc → dist/
+```

package/dist/address.js

@@ -16,7 +16,11 @@ export function createGltfElementAddress(json, type, index) {
     const anchor = parseAnchorValue(name);
     if (anchor)
         address.anchor = anchor;
-    if (name !== undefined)
+    // an empty name is non-information: resolution never reads `name` (id → anchor →
+    // namePath) and reconciliation falls back to the last namePath segment ("" again).
+    // NOTE: empty namePath SEGMENTS are load-bearing (positional child-walk) — only the
+    // standalone `name` field is dropped when empty.
+    if (name)
         address.name = name;
     if (type === "node") {
         const path = gltfNodeNamePath(json, index);
@@ -37,7 +41,8 @@ export function createObjectAddress(root, target) {
     const anchor = parseAnchorValue(target.name);
     if (anchor)
         address.anchor = anchor;
-    if (typeof target.name === "string")
+    // empty name dropped — see createGltfElementAddress; namePath segments stay verbatim
+    if (target.name)
         address.name = target.name;
     address.namePath = path.map(n => n.name ?? "");
     return address;

package/dist/anchor.d.ts

@@ -28,6 +28,18 @@ export type ParsedAnchor = {
  * Returns null when no marker matches or the anchor value is empty.
  */
 export declare function parseAnchor(rawName: string | null | undefined): ParsedAnchor | null;
+/**
+ * Names 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 a
+ * 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 are one name.
+ *
+ * Exported because id derivation applies the SAME rule to unanchored names (see
+ * {@link import("./id.js").idNameOf}) — one normalization, one change point.
+ */
+export declare function normalizeName(value: string): string;
 /**
  * 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.

package/dist/anchor.js

@@ -29,20 +29,23 @@ export function parseAnchor(rawName) {
     for (const marker of byLengthDescending(ANCHOR_MARKERS)) {
         if (!lower.endsWith(marker))
             continue;
-        const value = normalizeAnchorValue(trimmed.substring(0, trimmed.length - marker.length));
+        const value = normalizeName(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.
+ * Names 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 a
+ * 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 are one name.
+ *
+ * Exported because id derivation applies the SAME rule to unanchored names (see
+ * {@link import("./id.js").idNameOf}) — one normalization, one change point.
  */
-function normalizeAnchorValue(value) {
+export function normalizeName(value) {
     return value.replace(/[\s_]+/g, " ").trim();
 }
 /**

package/dist/gltf.js

@@ -1,4 +1,4 @@
-import { computeElementId } from "./id.js";
+import { computeElementId, idNameOf } from "./id.js";
 /** The glTF `extras` key carrying the persistent id. */
 export const NEEDLE_ID_KEY = "needle-id";
 /** All root-collection element types that receive ids, with their glTF collection key. */
@@ -30,15 +30,17 @@ export function ensureIds(json, options) {
             continue;
         // occurrence-of-name: the id input is the element's position among same-named
         // elements, NOT its collection index — uniquely named elements keep their ids
-        // across reorders and asset updates
+        // across reorders and asset updates. Grouping is by the DERIVATION name
+        // (anchor marker stripped, normalized), matching occurrenceOfName.
         const occurrences = new Map();
         for (let index = 0; index < elements.length; index++) {
             const element = elements[index];
             if (element == null || typeof element !== "object")
                 continue;
             const name = typeof element.name === "string" ? element.name : "";
-            const occurrence = occurrences.get(name) ?? 0;
-            occurrences.set(name, occurrence + 1);
+            const group = idNameOf(name);
+            const occurrence = occurrences.get(group) ?? 0;
+            occurrences.set(group, occurrence + 1);
             element.extras ?? (element.extras = {});
             if (element.extras[NEEDLE_ID_KEY] === undefined) {
                 element.extras[NEEDLE_ID_KEY] = computeElementId(type, name, occurrence, baseHash);

package/dist/id.d.ts

@@ -1,16 +1,32 @@
 /**
- * The deterministic needle-id of a glTF element.
+ * The name an id is derived FROM: the anchor marker removed (if any) and space/underscore
+ * runs collapsed.
  *
- * - Anchored name (`… #needle`): `uuidv5("<type>-<anchor>")` — survives ANY content
- *   change while the name stays.
- * - Otherwise: `uuidv5("<type>-<name>-<occurrence>[-<baseHash>]")` where `occurrence`
- *   is the element's position among SAME-NAMED elements of its type. Uniquely named
- *   elements are therefore fully reorder-stable across file versions; duplicates shift
- *   only when reordered within their own name group; unnamed elements are positional
- *   among the unnamed.
- * - `baseHash` is an optional consumer-supplied salt (e.g. an asset/content id) that
- *   scopes ids to an external identity. Omitted by default, so any tool stamping the
- *   same element mints the same id with no coordination.
+ * The marker is stripped because **ids are minted as if no anchor existed** — an anchor is
+ * a LABEL, not an identity, and the two must be able to change independently. Both halves
+ * of that are load-bearing:
+ * - stripping the marker means ADDING or REMOVING `#needle` leaves the id untouched (under
+ *   the previous rule, anchoring an object CHANGED its id — so the very act recommended for
+ *   making something stable orphaned every edit already addressed to it);
+ * - {@link occurrenceOfName} groups on this same value, so anchoring ONE of two `Door`s
+ *   does not shift the OTHER one's occurrence.
+ *
+ * Note what is decoupled: the id is independent of the anchor MARKER, not of the NAME.
+ * Renaming `Door #needle` → `Entrance #needle` still changes a DERIVED id; a STAMPED id is
+ * unaffected, since existing ids are never overwritten.
+ */
+export declare function idNameOf(name: string | null | undefined): string;
+/**
+ * The deterministic needle-id of a glTF element:
+ * `uuidv5("<type>-<idName>-<occurrence>[-<baseHash>]")`, where `idName` is the name with
+ * any anchor marker removed ({@link idNameOf}) and `occurrence` is the element's position
+ * among same-named elements of its type. Uniquely named elements are therefore fully
+ * reorder-stable across file versions; duplicates shift only when reordered within their
+ * own name group; unnamed elements are positional among the unnamed.
+ *
+ * `baseHash` is an optional consumer-supplied salt (e.g. an asset/content id) that scopes
+ * ids to an external identity. Omitted by default, so any tool stamping the same element
+ * mints the same id with no coordination.
  *
  * Ids are persisted in `extras["needle-id"]` and never overwritten once present —
  * whoever stamps first wins; this rule only governs never-stamped elements.
@@ -20,6 +36,9 @@ export declare function computeElementId(type: string, name: string | null | und
  * The occurrence of the element at `index` among same-named elements of its collection —
  * the positional input of {@link computeElementId}. Exposed so consumers computing ids
  * for individual elements (instead of stamping whole files) use the identical rule.
+ *
+ * Grouping is by {@link idNameOf}, so an anchored element counts in the same group as its
+ * unanchored namesakes.
  */
 export declare function occurrenceOfName(elements: ReadonlyArray<{
     name?: unknown;

package/dist/id.js

@@ -1,43 +1,60 @@
-import { parseAnchorValue } from "./anchor.js";
+import { normalizeName, parseAnchor } from "./anchor.js";
 import { uuidv5 } from "./uuid.js";
 /**
- * The deterministic needle-id of a glTF element.
+ * The name an id is derived FROM: the anchor marker removed (if any) and space/underscore
+ * runs collapsed.
  *
- * - Anchored name (`… #needle`): `uuidv5("<type>-<anchor>")` — survives ANY content
- *   change while the name stays.
- * - Otherwise: `uuidv5("<type>-<name>-<occurrence>[-<baseHash>]")` where `occurrence`
- *   is the element's position among SAME-NAMED elements of its type. Uniquely named
- *   elements are therefore fully reorder-stable across file versions; duplicates shift
- *   only when reordered within their own name group; unnamed elements are positional
- *   among the unnamed.
- * - `baseHash` is an optional consumer-supplied salt (e.g. an asset/content id) that
- *   scopes ids to an external identity. Omitted by default, so any tool stamping the
- *   same element mints the same id with no coordination.
+ * The marker is stripped because **ids are minted as if no anchor existed** — an anchor is
+ * a LABEL, not an identity, and the two must be able to change independently. Both halves
+ * of that are load-bearing:
+ * - stripping the marker means ADDING or REMOVING `#needle` leaves the id untouched (under
+ *   the previous rule, anchoring an object CHANGED its id — so the very act recommended for
+ *   making something stable orphaned every edit already addressed to it);
+ * - {@link occurrenceOfName} groups on this same value, so anchoring ONE of two `Door`s
+ *   does not shift the OTHER one's occurrence.
+ *
+ * Note what is decoupled: the id is independent of the anchor MARKER, not of the NAME.
+ * Renaming `Door #needle` → `Entrance #needle` still changes a DERIVED id; a STAMPED id is
+ * unaffected, since existing ids are never overwritten.
+ */
+export function idNameOf(name) {
+    if (typeof name !== "string")
+        return "";
+    // an anchor's value is already marker-stripped and normalized
+    return parseAnchor(name)?.value ?? normalizeName(name);
+}
+/**
+ * The deterministic needle-id of a glTF element:
+ * `uuidv5("<type>-<idName>-<occurrence>[-<baseHash>]")`, where `idName` is the name with
+ * any anchor marker removed ({@link idNameOf}) and `occurrence` is the element's position
+ * among same-named elements of its type. Uniquely named elements are therefore fully
+ * reorder-stable across file versions; duplicates shift only when reordered within their
+ * own name group; unnamed elements are positional among the unnamed.
+ *
+ * `baseHash` is an optional consumer-supplied salt (e.g. an asset/content id) that scopes
+ * ids to an external identity. Omitted by default, so any tool stamping the same element
+ * mints the same id with no coordination.
  *
  * Ids are persisted in `extras["needle-id"]` and never overwritten once present —
  * whoever stamps first wins; this rule only governs never-stamped elements.
  */
 export function computeElementId(type, name, occurrence, baseHash) {
-    const anchor = parseAnchorValue(name);
-    const str = anchor !== null
-        ? `${type}-${anchor}`
-        : `${type}-${name ? name : ""}-${occurrence}${baseHash ? `-${baseHash}` : ""}`;
-    return uuidv5(str);
+    return uuidv5(`${type}-${idNameOf(name)}-${occurrence}${baseHash ? `-${baseHash}` : ""}`);
 }
 /**
  * The occurrence of the element at `index` among same-named elements of its collection —
  * the positional input of {@link computeElementId}. Exposed so consumers computing ids
  * for individual elements (instead of stamping whole files) use the identical rule.
+ *
+ * Grouping is by {@link idNameOf}, so an anchored element counts in the same group as its
+ * unanchored namesakes.
  */
 export function occurrenceOfName(elements, index) {
-    const name = normalizedName(elements[index]);
+    const name = idNameOf(elements[index]?.name);
     let occurrence = 0;
     for (let i = 0; i < index; i++) {
-        if (normalizedName(elements[i]) === name)
+        if (idNameOf(elements[i]?.name) === name)
             occurrence++;
     }
     return occurrence;
 }
-function normalizedName(element) {
-    return typeof element?.name === "string" ? element.name : "";
-}

package/dist/index.d.ts

@@ -2,5 +2,5 @@ export { ANCHOR_MARKER, ANCHOR_MARKERS, parseAnchor, parseAnchorValue, type Pars
 export { computeElementId, occurrenceOfName } from "./id.js";
 export { ensureIds, getElementId, NEEDLE_ID_KEY, STAMPED_COLLECTIONS, type EnsureIdsOptions, type EnsureIdsResult, type GltfElement, type GltfJson, type StampedElementType, } from "./gltf.js";
 export { collectionKeyForType, createGltfElementAddress, createObjectAddress, findPath, type GraphNode, type NeedleAddress, } from "./address.js";
-export { reconcileInGraph, resolveInGltf, resolveInGraph, type GltfResolveResult, type ReconcileCandidate, } from "./resolve.js";
+export { reconcileInGraph, resolveInCollection, resolveInGltf, resolveInGraph, type AddressableElement, type GltfResolveResult, type ReconcileCandidate, type ResolutionIssue, type ResolutionRung, type ResolveOptions, } from "./resolve.js";
 export { randomUuid, uuidv5, UUID_NAMESPACE_URL } from "./uuid.js";

package/dist/index.js

@@ -2,5 +2,5 @@ export { ANCHOR_MARKER, ANCHOR_MARKERS, parseAnchor, parseAnchorValue } from "./
 export { computeElementId, occurrenceOfName } from "./id.js";
 export { ensureIds, getElementId, NEEDLE_ID_KEY, STAMPED_COLLECTIONS, } from "./gltf.js";
 export { collectionKeyForType, createGltfElementAddress, createObjectAddress, findPath, } from "./address.js";
-export { reconcileInGraph, resolveInGltf, resolveInGraph, } from "./resolve.js";
+export { reconcileInGraph, resolveInCollection, resolveInGltf, resolveInGraph, } from "./resolve.js";
 export { randomUuid, uuidv5, UUID_NAMESPACE_URL } from "./uuid.js";

package/dist/resolve.d.ts

@@ -6,16 +6,72 @@ export type GltfResolveResult = {
     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).
+ * Resolve an address inside glTF JSON. Same ladder as the live graph —
+ * **anchor → id → namePath** (nodes) — with the anchor winning only when it matches
+ * exactly one element. 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;
+export declare function resolveInGltf(address: NeedleAddress, json: GltfJson, options?: ResolveOptions): GltfResolveResult | null;
+/** which rung of the ladder produced (or could have produced) a match */
+export type ResolutionRung = "id" | "anchor" | "namePath" | "name";
+/**
+ * Something a caller may want to show a human. Never an error — resolution still returns
+ * its best answer; these say the answer was not the only defensible one.
+ */
+export type ResolutionIssue = 
+/** an anchor matched several elements, so it could not outrank an exact key */
+{
+    kind: "ambiguous-anchor";
+    anchor: string;
+    count: number;
+}
+/** a name matched several elements in a flat collection */
+ | {
+    kind: "ambiguous-name";
+    name: string;
+    count: number;
+}
+/** two rungs resolved to DIFFERENT elements — the content changed underneath */
+ | {
+    kind: "conflict";
+    preferred: ResolutionRung;
+    other: ResolutionRung;
+};
+export type ResolveOptions = {
+    /**
+     * Collect ambiguity/conflict evidence. OPT-IN because it costs extra traversals:
+     * detecting that two rungs disagree means evaluating both instead of stopping at the
+     * first hit, and resolution already walks from the root per address. The runtime
+     * short-circuits and pays nothing; the editor asks for evidence so it can surface
+     * drift to the user.
+     */
+    report?: (issue: ResolutionIssue) => void;
+};
 /**
  * Resolve an address inside a live scene graph (duck-typed — any three.js).
- * Same order as glTF resolution: id → anchor → namePath.
+ *
+ * Ladder: **anchor → id → namePath**. The anchor comes first because it is a deliberate,
+ * human-authored declaration, while an id may be a derived value whose basis shifted when
+ * the content changed. It only wins when it resolves UNIQUELY: anchors are labels and may
+ * legally repeat, and an ambiguous label must never outrank an exact key.
+ */
+export declare function resolveInGraph(address: NeedleAddress, root: GraphNode, options?: ResolveOptions): GraphNode | null;
+/** duck-typed view of an element that is not a graph node (a material, texture, …) */
+export type AddressableElement = {
+    name?: string;
+    userData?: Record<string, unknown>;
+};
+/**
+ * Resolve an address against a FLAT collection of live elements — materials, textures and
+ * anything else that carries a name and `userData` but is not part of the scene graph.
+ *
+ * Same ladder as the graph, minus `namePath` (there is no hierarchy to walk) plus `name`
+ * as the final rung, since a flat collection has no positional fallback. This exists so
+ * every element type resolves through ONE implementation: materials previously had their
+ * own ladders, could not be anchored at all, and disagreed with each other about whether a
+ * name match had to be unique.
  */
-export declare function resolveInGraph(address: NeedleAddress, root: GraphNode): GraphNode | null;
+export declare function resolveInCollection<T extends AddressableElement>(address: NeedleAddress, elements: readonly T[], options?: ResolveOptions): T | null;
 export type ReconcileCandidate = {
     object: GraphNode;
     /** 0..1 — heuristic, for ranking and thresholds; 1.0 is reserved for exact resolution */