@needle-tools/addressing 0.3.3 → 0.3.4

package/Readme.md

@@ -29,11 +29,11 @@ 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:
+`{ id, anchor?, type?, name?, path? }`. Resolution order is strict (path: "/"-separated segments, JSON-Pointer `~0`/`~1` escaping):
 
 1. `id` — exact match (`extras` in glTF JSON, `userData` in live scene graphs)
 2. `anchor` — survives asset updates
-3. `namePath` — best-effort structural match
+3. `path` — best-effort structural match
 4. **reconciliation** — never automatic: `reconcileInGraph` returns ranked candidates
    with confidence + reasons; the caller decides thresholds and whether to re-anchor.
 

package/dist/address.d.ts

@@ -4,7 +4,7 @@ import { type GltfJson, type StampedElementType } from "./gltf.js";
  * 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`
+ * Resolution order: `id` (exact) → `anchor` (survives asset updates) → `path`
  * (best-effort) → reconciliation (candidates + confidence, never a silent guess).
  */
 export type NeedleAddress = {
@@ -16,16 +16,31 @@ export type NeedleAddress = {
     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[];
+    /**
+     * Node names from the asset root (exclusive) down to the target (inclusive);
+     * nodes only. ONE path syntax everywhere (2026-08-03): `/`-separated segments
+     * with JSON-Pointer escaping (`~0` = `~`, `~1` = `/`) — see {@link joinPath} /
+     * {@link splitPath}. Empty SEGMENTS are load-bearing (positional walk over
+     * unnamed nodes), so `""` is a valid one-segment path — test `!== undefined`,
+     * never truthiness. ABSENT means "no path rung".
+     */
+    path?: string;
 };
+/** escape one segment for embedding in a path string */
+export declare function encodePathSegment(name: string): string;
+/** decode one path segment back to the literal name */
+export declare function decodePathSegment(segment: string): string;
+/** join literal segment names into an escaped path string */
+export declare function joinPath(segments: readonly string[]): string;
+/** split an escaped path string into literal segment names ("" → one empty segment) */
+export declare function splitPath(path: string): 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. */
+/** Build an address for a glTF root-collection element. `path` only applies to nodes. */
 export declare function createGltfElementAddress(json: GltfJson, type: StampedElementType | string, index: number): NeedleAddress | null;
 /** Build an address for a live scene-graph object under `root`. */
 export declare function createObjectAddress(root: GraphNode, target: GraphNode): NeedleAddress | null;

package/dist/address.js

@@ -1,6 +1,26 @@
 import { parseAnchorValue } from "./anchor.js";
-import { getElementId, NEEDLE_ID_KEY } from "./gltf.js";
-/** Build an address for a glTF root-collection element. `namePath` only applies to nodes. */
+import { getElementId, NEEDLE_ID_KEY } from "./id.js";
+// #region path segment syntax
+// The one path syntax of the project format (target.path uses the same rules):
+// "/" separates segments; a literal "~" in a name is written "~0", a literal "/"
+// is written "~1" (JSON-Pointer, RFC 6901). Escape order matters on decode.
+/** escape one segment for embedding in a path string */
+export function encodePathSegment(name) {
+    return name.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+/** decode one path segment back to the literal name */
+export function decodePathSegment(segment) {
+    return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+/** join literal segment names into an escaped path string */
+export function joinPath(segments) {
+    return segments.map(encodePathSegment).join("/");
+}
+/** split an escaped path string into literal segment names ("" → one empty segment) */
+export function splitPath(path) {
+    return path.split("/").map(decodePathSegment);
+}
+/** Build an address for a glTF root-collection element. `path` only applies to nodes. */
 export function createGltfElementAddress(json, type, index) {
     const collection = json[collectionKeyForType(type)];
     if (!Array.isArray(collection))
@@ -17,23 +37,23 @@ export function createGltfElementAddress(json, type, index) {
     if (anchor)
         address.anchor = anchor;
     // 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
+    // path) and reconciliation falls back to the last path segment ("" again).
+    // NOTE: empty path 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);
-        if (path)
-            address.namePath = path;
+        const segments = gltfNodeNamePath(json, index);
+        if (segments)
+            address.path = joinPath(segments);
     }
     return address;
 }
 /** Build an address for a live scene-graph object under `root`. */
 export function createObjectAddress(root, target) {
-    const path = findPath(root, target);
-    if (!path)
-        return null;
+    const nodes = findPath(root, target);
+    if (!nodes || nodes.length === 0)
+        return null; // the root itself has no path — address it by ref alone
     const address = { type: "node" };
     const id = target.userData?.[NEEDLE_ID_KEY];
     if (typeof id === "string")
@@ -41,10 +61,10 @@ export function createObjectAddress(root, target) {
     const anchor = parseAnchorValue(target.name);
     if (anchor)
         address.anchor = anchor;
-    // empty name dropped — see createGltfElementAddress; namePath segments stay verbatim
+    // empty name dropped — see createGltfElementAddress; path segments stay verbatim
     if (target.name)
         address.name = target.name;
-    address.namePath = path.map(n => n.name ?? "");
+    address.path = joinPath(nodes.map(n => n.name ?? ""));
     return address;
 }
 export function collectionKeyForType(type) {

package/dist/gltf.d.ts

@@ -1,5 +1,8 @@
-/** The glTF `extras` key carrying the persistent id. */
-export declare const NEEDLE_ID_KEY = "needle-id";
+/**
+ * Structural glTF shapes — the duck-typed views of a glTF JSON root and its
+ * elements, plus which collections carry ids. All id READING and MINTING lives
+ * in `id.ts`; this module only describes the file format.
+ */
 /** All root-collection element types that receive ids, with their glTF collection key. */
 export declare const STAMPED_COLLECTIONS: readonly [readonly ["node", "nodes"], readonly ["scene", "scenes"], readonly ["animation", "animations"], readonly ["camera", "cameras"], readonly ["material", "materials"], readonly ["mesh", "meshes"], readonly ["skin", "skins"], readonly ["texture", "textures"], readonly ["image", "images"], readonly ["sampler", "samplers"]];
 export type StampedElementType = (typeof STAMPED_COLLECTIONS)[number][0];
@@ -13,29 +16,3 @@ export type GltfElement = {
 export type GltfJson = {
     [collection: string]: unknown;
 };
-export type EnsureIdsOptions = {
-    /**
-     * Optional salt scoping unanchored ids to an external identity (e.g. an
-     * asset/content id). By default no salt is used — ids derive from the element alone
-     * (type, name, occurrence-of-name), so any tool mints the same ids with no
-     * coordination. With a salt, only writers that know it agree — safe because
-     * existing ids are never overwritten (whoever stamps first wins).
-     */
-    baseHash?: string;
-};
-export type EnsureIdsResult = {
-    /** the salt the ids were derived with, when one was provided */
-    baseHash?: string;
-    /** how many elements received a new id (0 → the file was already fully stamped) */
-    assigned: number;
-};
-/**
- * Idempotently inject `extras["needle-id"]` into every element of the stamped
- * collections. Existing ids are never overwritten, so already-stamped files pass
- * through unchanged and every id writer agrees with whoever stamped first.
- *
- * Mutates `json` in place.
- */
-export declare function ensureIds(json: GltfJson, options?: EnsureIdsOptions): EnsureIdsResult;
-/** Read an element's needle-id without computing anything. */
-export declare function getElementId(element: GltfElement | null | undefined): string | null;

package/dist/gltf.js

@@ -1,6 +1,8 @@
-import { computeElementId, idNameOf } from "./id.js";
-/** The glTF `extras` key carrying the persistent id. */
-export const NEEDLE_ID_KEY = "needle-id";
+/**
+ * Structural glTF shapes — the duck-typed views of a glTF JSON root and its
+ * elements, plus which collections carry ids. All id READING and MINTING lives
+ * in `id.ts`; this module only describes the file format.
+ */
 /** All root-collection element types that receive ids, with their glTF collection key. */
 export const STAMPED_COLLECTIONS = [
     ["node", "nodes"],
@@ -14,44 +16,3 @@ export const STAMPED_COLLECTIONS = [
     ["image", "images"],
     ["sampler", "samplers"],
 ];
-/**
- * Idempotently inject `extras["needle-id"]` into every element of the stamped
- * collections. Existing ids are never overwritten, so already-stamped files pass
- * through unchanged and every id writer agrees with whoever stamped first.
- *
- * Mutates `json` in place.
- */
-export function ensureIds(json, options) {
-    const baseHash = options?.baseHash;
-    let assigned = 0;
-    for (const [type, collection] of STAMPED_COLLECTIONS) {
-        const elements = json[collection];
-        if (!Array.isArray(elements))
-            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. 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 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);
-                assigned++;
-            }
-        }
-    }
-    return { baseHash, assigned };
-}
-/** Read an element's needle-id without computing anything. */
-export function getElementId(element) {
-    const id = element?.extras?.[NEEDLE_ID_KEY];
-    return typeof id === "string" ? id : null;
-}

package/dist/id.d.ts

@@ -1,3 +1,14 @@
+import { type GltfElement, type GltfJson } from "./gltf.js";
+import type { GraphNode } from "./address.js";
+/**
+ * THE identity module: every read and every mint of a needle-id lives here —
+ * derivation (deterministic ids for glTF elements), glTF stamping/readback
+ * (`extras`), and live-node stamping/readback (`userData`). Consumers never
+ * touch the key or mint ids themselves.
+ */
+/** The key carrying the persistent id — glTF `extras` for file elements, live
+ * `userData` for scene objects (exports copy one into the other). */
+export declare const NEEDLE_ID_KEY = "needle-id";
 /**
  * The name an id is derived FROM: the anchor marker removed (if any) and space/underscore
  * runs collapsed.
@@ -43,3 +54,52 @@ export declare function computeElementId(type: string, name: string | null | und
 export declare function occurrenceOfName(elements: ReadonlyArray<{
     name?: unknown;
 } | null | undefined>, index: number): number;
+export type EnsureIdsOptions = {
+    /**
+     * Optional salt scoping unanchored ids to an external identity (e.g. an
+     * asset/content id). By default no salt is used — ids derive from the element alone
+     * (type, name, occurrence-of-name), so any tool mints the same ids with no
+     * coordination. With a salt, only writers that know it agree — safe because
+     * existing ids are never overwritten (whoever stamps first wins).
+     */
+    baseHash?: string;
+};
+export type EnsureIdsResult = {
+    /** the salt the ids were derived with, when one was provided */
+    baseHash?: string;
+    /** how many elements received a new id (0 → the file was already fully stamped) */
+    assigned: number;
+};
+/**
+ * Idempotently inject `extras["needle-id"]` into every element of the stamped
+ * collections. Existing ids are never overwritten, so already-stamped files pass
+ * through unchanged and every id writer agrees with whoever stamped first.
+ *
+ * Mutates `json` in place.
+ */
+export declare function ensureIds(json: GltfJson, options?: EnsureIdsOptions): EnsureIdsResult;
+/** Read an element's needle-id without computing anything. */
+export declare function getElementId(element: GltfElement | null | undefined): string | null;
+/** Read a live node's needle-id from `userData` — the live-object counterpart of
+ * {@link getElementId}, which reads glTF `extras`. */
+export declare function getNodeId(target: GraphNode | null | undefined): string | null;
+/** Ensure a live node carries a needle-id: returns the existing one or MINTS a
+ * random uuid into `userData`. Random by design — editor-created (scratch) content
+ * has no derivation basis; the id persists because exports write `userData` ids
+ * into glTF `extras` (create → save → reload sees the same id). */
+export declare function ensureNodeId(target: GraphNode): string;
+export type ShedIdentityOptions = {
+    /** additional identity keys deleted from every `userData.components` entry —
+     * the caller names its component-identity keys (e.g. an engine's editor-guid
+     * key); addressing owns the traversal and the needle-id rule */
+    componentKeys?: readonly string[];
+};
+/**
+ * Shed a subtree's AUTHORED identity — for clones (duplicate/paste) before they are
+ * re-stamped. Stamped needle-ids are deleted on every node: sibling id collisions
+ * break addressing (an id-addressed edit resolves to whichever holder comes first).
+ * With `componentKeys`, the same keys are deleted from `userData.components`
+ * entries (a copied component guid would bake the ORIGINAL's identity into the
+ * clone's next export). Fresh ids are minted by whatever stamps next.
+ */
+export declare function shedNodeIdentity(root: GraphNode, options?: ShedIdentityOptions): void;

package/dist/id.js

@@ -1,5 +1,16 @@
 import { normalizeName, parseAnchor } from "./anchor.js";
-import { uuidv5 } from "./uuid.js";
+import { STAMPED_COLLECTIONS } from "./gltf.js";
+import { randomUuid, uuidv5 } from "./uuid.js";
+/**
+ * THE identity module: every read and every mint of a needle-id lives here —
+ * derivation (deterministic ids for glTF elements), glTF stamping/readback
+ * (`extras`), and live-node stamping/readback (`userData`). Consumers never
+ * touch the key or mint ids themselves.
+ */
+/** The key carrying the persistent id — glTF `extras` for file elements, live
+ * `userData` for scene objects (exports copy one into the other). */
+export const NEEDLE_ID_KEY = "needle-id";
+// #region Derivation
 /**
  * The name an id is derived FROM: the anchor marker removed (if any) and space/underscore
  * runs collapsed.
@@ -58,3 +69,98 @@ export function occurrenceOfName(elements, index) {
     }
     return occurrence;
 }
+/**
+ * Idempotently inject `extras["needle-id"]` into every element of the stamped
+ * collections. Existing ids are never overwritten, so already-stamped files pass
+ * through unchanged and every id writer agrees with whoever stamped first.
+ *
+ * Mutates `json` in place.
+ */
+export function ensureIds(json, options) {
+    const baseHash = options?.baseHash;
+    let assigned = 0;
+    for (const [type, collection] of STAMPED_COLLECTIONS) {
+        const elements = json[collection];
+        if (!Array.isArray(elements))
+            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. 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 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);
+                assigned++;
+            }
+        }
+    }
+    return { baseHash, assigned };
+}
+/** Read an element's needle-id without computing anything. */
+export function getElementId(element) {
+    const id = element?.extras?.[NEEDLE_ID_KEY];
+    return typeof id === "string" ? id : null;
+}
+// #endregion
+// #region Live nodes (userData)
+/** Read a live node's needle-id from `userData` — the live-object counterpart of
+ * {@link getElementId}, which reads glTF `extras`. */
+export function getNodeId(target) {
+    const id = target?.userData?.[NEEDLE_ID_KEY];
+    return typeof id === "string" ? id : null;
+}
+/** Ensure a live node carries a needle-id: returns the existing one or MINTS a
+ * random uuid into `userData`. Random by design — editor-created (scratch) content
+ * has no derivation basis; the id persists because exports write `userData` ids
+ * into glTF `extras` (create → save → reload sees the same id). */
+export function ensureNodeId(target) {
+    const userData = (target.userData ?? (target.userData = {}));
+    const existing = userData[NEEDLE_ID_KEY];
+    if (typeof existing === "string")
+        return existing;
+    const id = randomUuid();
+    userData[NEEDLE_ID_KEY] = id;
+    return id;
+}
+/**
+ * Shed a subtree's AUTHORED identity — for clones (duplicate/paste) before they are
+ * re-stamped. Stamped needle-ids are deleted on every node: sibling id collisions
+ * break addressing (an id-addressed edit resolves to whichever holder comes first).
+ * With `componentKeys`, the same keys are deleted from `userData.components`
+ * entries (a copied component guid would bake the ORIGINAL's identity into the
+ * clone's next export). Fresh ids are minted by whatever stamps next.
+ */
+export function shedNodeIdentity(root, options) {
+    const componentKeys = options?.componentKeys ?? [];
+    const visit = (node) => {
+        const userData = node.userData;
+        if (userData) {
+            if (typeof userData[NEEDLE_ID_KEY] === "string")
+                delete userData[NEEDLE_ID_KEY];
+            const components = userData["components"];
+            if (Array.isArray(components)) {
+                for (const component of components) {
+                    if (!component || typeof component !== "object")
+                        continue;
+                    for (const key of componentKeys) {
+                        if (component[key] !== undefined)
+                            delete component[key];
+                    }
+                }
+            }
+        }
+        for (const child of node.children ?? [])
+            visit(child);
+    };
+    visit(root);
+}
+// #endregion

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { ANCHOR_MARKER, ANCHOR_MARKERS, parseAnchor, parseAnchorValue, type ParsedAnchor } from "./anchor.js";
-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 { computeElementId, ensureIds, ensureNodeId, getElementId, getNodeId, NEEDLE_ID_KEY, occurrenceOfName, shedNodeIdentity, type EnsureIdsOptions, type EnsureIdsResult, type ShedIdentityOptions, } from "./id.js";
+export { STAMPED_COLLECTIONS, type GltfElement, type GltfJson, type StampedElementType, } from "./gltf.js";
+export { collectionKeyForType, createGltfElementAddress, createObjectAddress, decodePathSegment, encodePathSegment, findPath, joinPath, splitPath, type GraphNode, type NeedleAddress, } from "./address.js";
 export { reconcileInGraph, resolveInCollection, resolveInGltf, resolveInGraph, type AddressableElement, type GltfResolveResult, type ReconcileCandidate, type ResolutionIssue, type ResolutionRung, type ResolveOptions, } from "./resolve.js";
+export { targetFromString, targetToString, type AddressTarget } from "./target.js";
 export { randomUuid, uuidv5, UUID_NAMESPACE_URL } from "./uuid.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 export { ANCHOR_MARKER, ANCHOR_MARKERS, parseAnchor, parseAnchorValue } from "./anchor.js";
-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 { computeElementId, ensureIds, ensureNodeId, getElementId, getNodeId, NEEDLE_ID_KEY, occurrenceOfName, shedNodeIdentity, } from "./id.js";
+export { STAMPED_COLLECTIONS, } from "./gltf.js";
+export { collectionKeyForType, createGltfElementAddress, createObjectAddress, decodePathSegment, encodePathSegment, findPath, joinPath, splitPath, } from "./address.js";
 export { reconcileInGraph, resolveInCollection, resolveInGltf, resolveInGraph, } from "./resolve.js";
+export { targetFromString, targetToString } from "./target.js";
 export { randomUuid, uuidv5, UUID_NAMESPACE_URL } from "./uuid.js";

package/dist/resolve.d.ts

@@ -7,13 +7,13 @@ export type GltfResolveResult = {
 };
 /**
  * Resolve an address inside glTF JSON. Same ladder as the live graph —
- * **anchor → id → namePath** (nodes) — with the anchor winning only when it matches
+ * **anchor → id → path** (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, options?: ResolveOptions): GltfResolveResult | null;
 /** which rung of the ladder produced (or could have produced) a match */
-export type ResolutionRung = "id" | "anchor" | "namePath" | "name";
+export type ResolutionRung = "id" | "anchor" | "path" | "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.
@@ -50,7 +50,7 @@ export type ResolveOptions = {
 /**
  * Resolve an address inside a live scene graph (duck-typed — any three.js).
  *
- * Ladder: **anchor → id → namePath**. The anchor comes first because it is a deliberate,
+ * Ladder: **anchor → id → path**. 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.
@@ -65,7 +65,7 @@ export type AddressableElement = {
  * 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`
+ * Same ladder as the graph, minus `path` (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
@@ -81,6 +81,6 @@ export type ReconcileCandidate = {
 /**
  * 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.
+ * path still matches. Callers decide thresholds and whether to re-anchor.
  */
 export declare function reconcileInGraph(address: NeedleAddress, root: GraphNode): ReconcileCandidate[];

package/dist/resolve.js

@@ -1,9 +1,10 @@
 import { parseAnchorValue } from "./anchor.js";
-import { collectionKeyForType } from "./address.js";
-import { NEEDLE_ID_KEY, STAMPED_COLLECTIONS } from "./gltf.js";
+import { collectionKeyForType, splitPath } from "./address.js";
+import { NEEDLE_ID_KEY } from "./id.js";
+import { STAMPED_COLLECTIONS } from "./gltf.js";
 /**
  * Resolve an address inside glTF JSON. Same ladder as the live graph —
- * **anchor → id → namePath** (nodes) — with the anchor winning only when it matches
+ * **anchor → id → path** (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).
  */
@@ -49,8 +50,8 @@ export function resolveInGltf(address, json, options) {
     }
     if (byId)
         return byId;
-    if (address.namePath?.length && (!address.type || address.type === "node")) {
-        const index = walkGltfNamePath(json, address.namePath);
+    if (address.path !== undefined && (!address.type || address.type === "node")) {
+        const index = walkGltfNamePath(json, splitPath(address.path));
         if (index !== null) {
             const nodes = json["nodes"];
             return { type: "node", index, element: nodes[index] };
@@ -61,7 +62,7 @@ export function resolveInGltf(address, json, options) {
 /**
  * Resolve an address inside a live scene graph (duck-typed — any three.js).
  *
- * Ladder: **anchor → id → namePath**. The anchor comes first because it is a deliberate,
+ * Ladder: **anchor → id → path**. 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.
@@ -91,9 +92,9 @@ export function resolveInGraph(address, root, options) {
     }
     if (byId)
         return byId;
-    if (address.namePath?.length) {
+    if (address.path !== undefined) {
         let current = root;
-        for (const segment of address.namePath) {
+        for (const segment of splitPath(address.path)) {
             current = current.children?.find(c => (c.name ?? "") === segment) ?? null;
             if (!current)
                 break;
@@ -107,7 +108,7 @@ export function resolveInGraph(address, root, options) {
  * 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`
+ * Same ladder as the graph, minus `path` (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
@@ -145,20 +146,21 @@ export function resolveInCollection(address, elements, options) {
 /**
  * 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.
+ * path still matches. Callers decide thresholds and whether to re-anchor.
  */
 export function reconcileInGraph(address, root) {
-    if (!address.name && !address.namePath?.length)
+    const addressSegments = address.path !== undefined ? splitPath(address.path) : null;
+    if (!address.name && !addressSegments?.length)
         return [];
-    const targetName = address.name ?? address.namePath[address.namePath.length - 1];
+    const targetName = address.name ?? addressSegments[addressSegments.length - 1];
     const candidates = [];
-    collectDescendants(root, (node, namePath) => {
+    collectDescendants(root, (node, segments) => {
         if ((node.name ?? "") !== targetName)
             return;
         const reasons = [`name matches "${targetName}"`];
         let confidence = 0.5;
-        if (address.namePath?.length) {
-            const similarity = pathSuffixSimilarity(address.namePath, namePath);
+        if (addressSegments?.length) {
+            const similarity = pathSuffixSimilarity(addressSegments, segments);
             confidence += 0.4 * similarity;
             if (similarity > 0)
                 reasons.push(`path suffix similarity ${(similarity * 100).toFixed(0)}%`);
@@ -197,7 +199,7 @@ function findInCollection(json, key, predicate) {
     }
     return null;
 }
-function walkGltfNamePath(json, namePath) {
+function walkGltfNamePath(json, segments) {
     const nodes = json["nodes"];
     const scenes = json["scenes"];
     if (!Array.isArray(nodes) || !Array.isArray(scenes))
@@ -205,7 +207,7 @@ function walkGltfNamePath(json, namePath) {
     // 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) {
+    for (const segment of segments) {
         match = candidates.find(i => ((nodes[i]?.name ?? "") === segment)) ?? null;
         if (match === null)
             return null;
@@ -259,19 +261,19 @@ function findInGraph(root, predicate, visited = new Set()) {
 /** 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) => {
+    const walk = (node, segments) => {
         if (visited.has(node))
             return;
         visited.add(node);
         if (node !== root)
-            visit(node, namePath);
+            visit(node, segments);
         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(child, [...segments, child.name ?? ""]);
         }
     };
     walk(root, []);

package/dist/target.d.ts

@@ -0,0 +1,29 @@
+import type { NeedleAddress } from "./address.js";
+/**
+ * The canonical STRING form of a document target — the ONE print/parse pair
+ * for `{ ref?, address? }` (plans/one-address-vocabulary.md: one vocabulary;
+ * this is a second wire FORM of it, never a second dialect — no other code
+ * may format or parse these tokens).
+ *
+ * Grammar (rungs optional, fixed order):
+ *
+ *     "@" [ref] [ "/" [type ":"] [id] ["#" anchor] ["~" name] ["!" path] ]
+ *
+ * - `@` leads every token — the RETIRED session grammars ("<uuid>/<path>"
+ *   handles, bare hierarchy ids) can never half-parse as a target; a stale
+ *   token fails loud.
+ * - the `node` type is implicit (omitted on print, re-minted on parse) —
+ *   the canonical form normalizes a type-less address to `type: "node"`.
+ * - ref/id/anchor/name are token-escaped; the PATH rung is last and
+ *   verbatim (it is already the stored escaped form from joinPath and may
+ *   contain any character).
+ */
+export type AddressTarget = {
+    ref?: string;
+    address?: NeedleAddress;
+};
+/** print a target as its canonical token — null when there is nothing to name */
+export declare function targetToString(target: AddressTarget): string | null;
+/** parse a canonical token back to the target — null for anything this module
+ * did not print (retired grammars, garbage): a loud miss, never a half-parse */
+export declare function targetFromString(token: string): AddressTarget | null;