@needle-tools/addressing 0.3.1 → 0.3.3

package/Readme.md

@@ -13,7 +13,8 @@ meshes, skins, textures, images, samplers) can carry a UUID in `extras["needle-i
 
 - **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.
+  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

package/dist/address.d.ts

@@ -0,0 +1,34 @@
+import { 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 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;
+export declare function collectionKeyForType(type: string): string;
+/** path from root (exclusive) to target (inclusive), or null if target is not under root */
+export declare function findPath(root: GraphNode, target: GraphNode): GraphNode[] | null;

package/dist/address.js

@@ -0,0 +1,94 @@
+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. */
+export function createGltfElementAddress(json, type, index) {
+    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 = { type };
+    const id = getElementId(element);
+    if (id)
+        address.id = id;
+    const anchor = parseAnchorValue(name);
+    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
+    // 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;
+    }
+    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 address = { 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;
+    // 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;
+}
+export function collectionKeyForType(type) {
+    // 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, nodeIndex) {
+    const nodes = json["nodes"];
+    if (!Array.isArray(nodes))
+        return null;
+    const parents = new Map();
+    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 = [];
+    let current = nodeIndex;
+    const seen = new Set();
+    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, target) {
+    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/dist/anchor.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 declare 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 declare const ANCHOR_MARKERS: readonly string[];
+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 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.
+ */
+export declare function parseAnchorValue(rawName: string | null | undefined): string | null;

package/dist/anchor.js

@@ -0,0 +1,60 @@
+/**
+ * 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 = [ANCHOR_MARKER];
+/**
+ * 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) {
+    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 = normalizeName(trimmed.substring(0, trimmed.length - marker.length));
+        return value.length > 0 ? { marker, value } : null;
+    }
+    return 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 function normalizeName(value) {
+    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) {
+    return parseAnchor(rawName)?.value ?? null;
+}
+function byLengthDescending(markers) {
+    return markers.length > 1 ? [...markers].sort((a, b) => b.length - a.length) : markers;
+}

package/dist/gltf.d.ts

@@ -0,0 +1,41 @@
+/** The glTF `extras` key carrying the persistent id. */
+export declare const NEEDLE_ID_KEY = "needle-id";
+/** 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];
+/** Structural (duck-typed) view of a glTF root element — no glTF library dependency. */
+export type GltfElement = {
+    name?: string;
+    extras?: Record<string, unknown>;
+    [key: string]: unknown;
+};
+/** Structural view of a glTF JSON root. Collections are looked up by key. */
+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

@@ -0,0 +1,57 @@
+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. */
+export const STAMPED_COLLECTIONS = [
+    ["node", "nodes"],
+    ["scene", "scenes"],
+    ["animation", "animations"],
+    ["camera", "cameras"],
+    ["material", "materials"],
+    ["mesh", "meshes"],
+    ["skin", "skins"],
+    ["texture", "textures"],
+    ["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/hash.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Vendored SHA-1 so the package has zero runtime dependencies — it backs UUIDv5
+ * (RFC 4122). Correctness is pinned by golden tests against the `uuid` npm package.
+ */
+/** SHA-1 digest bytes of `data`. */
+export declare function sha1(data: Uint8Array): Uint8Array;
+export declare function toHex(bytes: Uint8Array): string;

package/dist/hash.js

@@ -0,0 +1,75 @@
+/**
+ * Vendored SHA-1 so the package has zero runtime dependencies — it backs UUIDv5
+ * (RFC 4122). Correctness is pinned by golden tests against the `uuid` npm package.
+ */
+/** SHA-1 digest bytes of `data`. */
+export function sha1(data) {
+    const padded = padMessage(data);
+    const dv = new DataView(padded.buffer, padded.byteOffset, padded.byteLength);
+    let h0 = 0x67452301, h1 = 0xefcdab89, h2 = 0x98badcfe, h3 = 0x10325476, h4 = 0xc3d2e1f0;
+    const w = new Uint32Array(80);
+    for (let off = 0; off < padded.length; off += 64) {
+        for (let i = 0; i < 16; i++)
+            w[i] = dv.getUint32(off + i * 4);
+        for (let i = 16; i < 80; i++) {
+            const n = w[i - 3] ^ w[i - 8] ^ w[i - 14] ^ w[i - 16];
+            w[i] = (n << 1) | (n >>> 31);
+        }
+        let a = h0, b = h1, c = h2, d = h3, e = h4;
+        for (let i = 0; i < 80; i++) {
+            let f, k;
+            if (i < 20) {
+                f = (b & c) | (~b & d);
+                k = 0x5a827999;
+            }
+            else if (i < 40) {
+                f = b ^ c ^ d;
+                k = 0x6ed9eba1;
+            }
+            else if (i < 60) {
+                f = (b & c) | (b & d) | (c & d);
+                k = 0x8f1bbcdc;
+            }
+            else {
+                f = b ^ c ^ d;
+                k = 0xca62c1d6;
+            }
+            const t = ((((a << 5) | (a >>> 27)) + f + e + k + w[i]) | 0);
+            e = d;
+            d = c;
+            c = (b << 30) | (b >>> 2);
+            b = a;
+            a = t;
+        }
+        h0 = (h0 + a) | 0;
+        h1 = (h1 + b) | 0;
+        h2 = (h2 + c) | 0;
+        h3 = (h3 + d) | 0;
+        h4 = (h4 + e) | 0;
+    }
+    const out = new Uint8Array(20);
+    const odv = new DataView(out.buffer);
+    odv.setUint32(0, h0 >>> 0);
+    odv.setUint32(4, h1 >>> 0);
+    odv.setUint32(8, h2 >>> 0);
+    odv.setUint32(12, h3 >>> 0);
+    odv.setUint32(16, h4 >>> 0);
+    return out;
+}
+export function toHex(bytes) {
+    let s = "";
+    for (let i = 0; i < bytes.length; i++)
+        s += bytes[i].toString(16).padStart(2, "0");
+    return s;
+}
+/** append 0x80, zero-pad to 56 mod 64, append big-endian 64-bit bit-length */
+function padMessage(data) {
+    const bitLen = data.length * 8;
+    const padded = new Uint8Array((((data.length + 8) >> 6) + 1) * 64);
+    padded.set(data);
+    padded[data.length] = 0x80;
+    const dv = new DataView(padded.buffer);
+    dv.setUint32(padded.length - 8, Math.floor(bitLen / 0x100000000));
+    dv.setUint32(padded.length - 4, bitLen >>> 0);
+    return padded;
+}

package/dist/id.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The name an id is derived FROM: the anchor marker removed (if any) and space/underscore
+ * runs collapsed.
+ *
+ * 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.
+ */
+export declare function computeElementId(type: string, name: string | null | undefined, occurrence: number, baseHash?: string): string;
+/**
+ * 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;
+} | null | undefined>, index: number): number;

package/dist/id.js

@@ -0,0 +1,60 @@
+import { normalizeName, parseAnchor } from "./anchor.js";
+import { uuidv5 } from "./uuid.js";
+/**
+ * The name an id is derived FROM: the anchor marker removed (if any) and space/underscore
+ * runs collapsed.
+ *
+ * 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) {
+    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 = idNameOf(elements[index]?.name);
+    let occurrence = 0;
+    for (let i = 0; i < index; i++) {
+        if (idNameOf(elements[i]?.name) === name)
+            occurrence++;
+    }
+    return occurrence;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+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 { 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

@@ -0,0 +1,6 @@
+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 { reconcileInGraph, resolveInCollection, resolveInGltf, resolveInGraph, } from "./resolve.js";
+export { randomUuid, uuidv5, UUID_NAMESPACE_URL } from "./uuid.js";

package/dist/resolve.d.ts

@@ -0,0 +1,86 @@
+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. 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, 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).
+ *
+ * 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 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 */
+    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[];