@needle-tools/addressing 0.3.4 → 0.4.0

package/dist/document/validation.js

@@ -0,0 +1,219 @@
+/**
+ * Structural validation of Needle project documents against the JSON Schema in
+ * `schema.json` — the format's machine-readable spec.
+ *
+ * The schema is the SINGLE source of truth: this file interprets it, it does not
+ * restate it. That is the whole point — a hand-written second validator would drift
+ * from the schema exactly like the plan's example drifted from the types.
+ *
+ * Deliberately dependency-free (a JSON Schema library is a lot of surface for the
+ * handful of keywords this schema uses), and STRICT about that: any keyword the
+ * schema uses and this interpreter does not implement THROWS. A validator that
+ * silently ignores keywords it doesn't know is worse than no validator — it reports
+ * "valid" for documents it never actually checked. If you extend the schema with a
+ * new keyword, this file fails loudly until you implement it.
+ *
+ * This validates SHAPE, not resolvability: whether an address actually hits a node in
+ * the loaded content is the evaluator's job (it reports issues and skips the arc).
+ */
+/** keywords that carry no constraint — annotations, identity, and the definition bag */
+const IGNORED_KEYWORDS = new Set(["$schema", "$id", "$comment", "title", "description", "default", "examples", "definitions"]);
+/** keywords this interpreter implements; anything else in the schema is a hard error */
+const SUPPORTED_KEYWORDS = new Set([
+    "$ref", "type", "enum", "const", "required", "properties", "additionalProperties",
+    "items", "minItems", "maxItems", "minLength", "allOf", "anyOf", "not",
+]);
+/**
+ * Validate `value` against `schema`. Returns every error found (not just the first) —
+ * a writer regression usually shows up as several related failures and seeing them
+ * together is what makes the cause obvious.
+ *
+ * @throws if the schema uses a keyword this interpreter does not implement.
+ */
+export function validateAgainstSchema(schema, value) {
+    const errors = [];
+    validateNode(schema, value, "", schema, errors);
+    return errors;
+}
+/** one-line-per-error rendering for assertion messages */
+export function formatSchemaErrors(errors) {
+    return errors.map(e => `  ${e.path || "<root>"}: ${e.message}`).join("\n");
+}
+function validateNode(schema, value, path, root, errors) {
+    for (const keyword of Object.keys(schema)) {
+        if (IGNORED_KEYWORDS.has(keyword) || SUPPORTED_KEYWORDS.has(keyword))
+            continue;
+        throw new Error(`projectDocumentValidation: unsupported JSON Schema keyword "${keyword}" at "${path || "<root>"}" — implement it before using it in the schema`);
+    }
+    assertWellFormed(schema, path);
+    if (typeof schema.$ref === "string") {
+        validateNode(resolveRef(schema.$ref, root), value, path, root, errors);
+        // sibling keywords next to $ref are ignored in draft-07 — our schema never mixes them
+        return;
+    }
+    if (schema.type !== undefined && !matchesType(schema.type, value)) {
+        errors.push({ path, message: `expected type ${JSON.stringify(schema.type)}, got ${describe(value)}` });
+        return; // every remaining keyword assumes the type held — reporting them too is noise
+    }
+    if (Array.isArray(schema.enum) && !schema.enum.some(candidate => deepEquals(candidate, value))) {
+        errors.push({ path, message: `expected one of ${JSON.stringify(schema.enum)}, got ${describe(value)}` });
+    }
+    if ("const" in schema && !deepEquals(schema.const, value)) {
+        errors.push({ path, message: `expected ${JSON.stringify(schema.const)}, got ${describe(value)}` });
+    }
+    if (typeof schema.minLength === "number" && typeof value === "string" && value.length < schema.minLength) {
+        errors.push({ path, message: `expected at least ${schema.minLength} character(s), got ${value.length}` });
+    }
+    if (Array.isArray(value)) {
+        if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+            errors.push({ path, message: `expected at least ${schema.minItems} item(s), got ${value.length}` });
+        }
+        if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
+            errors.push({ path, message: `expected at most ${schema.maxItems} item(s), got ${value.length}` });
+        }
+        if (isSchema(schema.items)) {
+            for (let i = 0; i < value.length; i++)
+                validateNode(schema.items, value[i], join(path, String(i)), root, errors);
+        }
+    }
+    if (isPlainObject(value)) {
+        if (Array.isArray(schema.required)) {
+            for (const key of schema.required) {
+                if (typeof key === "string" && !(key in value)) {
+                    errors.push({ path, message: `missing required property "${key}"` });
+                }
+            }
+        }
+        const properties = isPlainObject(schema.properties) ? schema.properties : undefined;
+        if (properties) {
+            for (const [key, sub] of Object.entries(properties)) {
+                if (key in value && isSchema(sub))
+                    validateNode(sub, value[key], join(path, key), root, errors);
+            }
+        }
+        const additional = schema.additionalProperties;
+        if (additional === false || isSchema(additional)) {
+            for (const [key, entry] of Object.entries(value)) {
+                if (properties && key in properties)
+                    continue;
+                if (additional === false) {
+                    errors.push({ path: join(path, key), message: "unexpected property" });
+                }
+                else {
+                    validateNode(additional, entry, join(path, key), root, errors);
+                }
+            }
+        }
+    }
+    if (Array.isArray(schema.allOf)) {
+        for (const sub of schema.allOf)
+            if (isSchema(sub))
+                validateNode(sub, value, path, root, errors);
+    }
+    if (Array.isArray(schema.anyOf)) {
+        const matched = schema.anyOf.some(sub => isSchema(sub) && validateAgainstSchemaIn(sub, value, root).length === 0);
+        if (!matched)
+            errors.push({ path, message: "matched none of the allowed forms (anyOf)" });
+    }
+    if (isSchema(schema.not) && validateAgainstSchemaIn(schema.not, value, root).length === 0) {
+        // our schema uses `not: {}` to mark RETIRED fields — say so rather than leaking
+        // "must not match the empty schema" at the reader
+        const why = typeof schema.description === "string" ? schema.description : "value is not allowed here";
+        errors.push({ path, message: why });
+    }
+}
+/**
+ * A keyword whose VALUE has an unexpected shape would be skipped by the checks below —
+ * the same silent-pass hazard as an unknown keyword, so it is the same hard error.
+ */
+function assertWellFormed(schema, path) {
+    const bad = (keyword, expected) => {
+        throw new Error(`projectDocumentValidation: "${keyword}" at "${path || "<root>"}" must be ${expected}`);
+    };
+    if ("$ref" in schema && typeof schema.$ref !== "string")
+        bad("$ref", "a string");
+    if ("type" in schema && typeof schema.type !== "string" && !Array.isArray(schema.type))
+        bad("type", "a string or array of strings");
+    if ("enum" in schema && !Array.isArray(schema.enum))
+        bad("enum", "an array");
+    if ("required" in schema && !Array.isArray(schema.required))
+        bad("required", "an array");
+    if ("properties" in schema && !isPlainObject(schema.properties))
+        bad("properties", "an object");
+    if ("items" in schema && !isPlainObject(schema.items))
+        bad("items", "a schema object (tuple form is not supported)");
+    if ("not" in schema && !isPlainObject(schema.not))
+        bad("not", "a schema object");
+    if ("allOf" in schema && !Array.isArray(schema.allOf))
+        bad("allOf", "an array");
+    if ("anyOf" in schema && !Array.isArray(schema.anyOf))
+        bad("anyOf", "an array");
+    if ("additionalProperties" in schema && typeof schema.additionalProperties !== "boolean" && !isPlainObject(schema.additionalProperties))
+        bad("additionalProperties", "a boolean or schema object");
+    for (const keyword of ["minItems", "maxItems", "minLength"]) {
+        if (keyword in schema && typeof schema[keyword] !== "number")
+            bad(keyword, "a number");
+    }
+}
+/** sub-validation that keeps the same `$ref` root (used by anyOf/not) */
+function validateAgainstSchemaIn(schema, value, root) {
+    const errors = [];
+    validateNode(schema, value, "", root, errors);
+    return errors;
+}
+function resolveRef(ref, root) {
+    if (!ref.startsWith("#/"))
+        throw new Error(`projectDocumentValidation: only local "#/..." $refs are supported, got "${ref}"`);
+    let current = root;
+    for (const segment of ref.slice(2).split("/")) {
+        if (!isPlainObject(current))
+            throw new Error(`projectDocumentValidation: $ref "${ref}" does not resolve`);
+        current = current[decodeURIComponent(segment.replace(/~1/g, "/").replace(/~0/g, "~"))];
+    }
+    if (!isSchema(current))
+        throw new Error(`projectDocumentValidation: $ref "${ref}" does not resolve to a schema`);
+    return current;
+}
+function matchesType(type, value) {
+    if (Array.isArray(type))
+        return type.some(t => matchesType(t, value));
+    switch (type) {
+        case "object": return isPlainObject(value);
+        case "array": return Array.isArray(value);
+        case "string": return typeof value === "string";
+        case "number": return typeof value === "number" && Number.isFinite(value);
+        case "integer": return typeof value === "number" && Number.isInteger(value);
+        case "boolean": return typeof value === "boolean";
+        case "null": return value === null;
+        default: throw new Error(`projectDocumentValidation: unsupported "type" value ${JSON.stringify(type)}`);
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isSchema(value) {
+    return isPlainObject(value);
+}
+function join(path, segment) {
+    return path ? `${path}/${segment}` : segment;
+}
+function describe(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    if (value === undefined)
+        return "undefined";
+    return typeof value;
+}
+function deepEquals(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.length === b.length && a.every((v, i) => deepEquals(v, b[i]));
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const keys = Object.keys(a);
+        return keys.length === Object.keys(b).length && keys.every(k => k in b && deepEquals(a[k], b[k]));
+    }
+    return false;
+}

package/dist/document/write.d.ts

@@ -0,0 +1,31 @@
+import type { NeedleAddress } from "../address.js";
+import type { ProjectDocumentOver, ProjectDocumentTarget } from "./types.js";
+export interface PropertyOverInput {
+    readonly target: ProjectDocumentTarget;
+    readonly value: unknown;
+    readonly previousValue: unknown;
+    readonly sequence?: number;
+    readonly alwaysWrite?: boolean;
+}
+export type PropertyOverResult = {
+    over: ProjectDocumentOver;
+    sequence: number;
+} | {
+    reverted: ProjectDocumentOver;
+} | {
+    issue: string;
+};
+/** Serialize one captured edit; adapters supply ownership and live-target checks. */
+export declare function writePropertyOver(input: PropertyOverInput, encodeNode?: (object: object) => unknown): PropertyOverResult;
+export declare function isDocumentReferenceValue(value: unknown): value is {
+    ref: string;
+    address?: NeedleAddress;
+};
+export declare function captureDocumentValue(value: unknown, encodeNode?: (object: object) => unknown): unknown;
+export declare function documentOverKey(over: ProjectDocumentOver): string;
+/**
+ * Merge base-document overs with freshly captured ones: a new over SUPERSEDES a base
+ * over on the same target (the user re-edited it); base overs whose reference is gone
+ * are dropped; everything else is preserved.
+ */
+export declare function mergeDocumentOvers(baseOvers: readonly ProjectDocumentOver[], newOvers: readonly ProjectDocumentOver[], liveRefs: ReadonlySet<string>, contentRefIds: ReadonlySet<string>, alwaysSuperseded?: ReadonlySet<string>, skipped?: string[]): ProjectDocumentOver[];

package/dist/document/write.js

@@ -0,0 +1,106 @@
+/** Serialize one captured edit; adapters supply ownership and live-target checks. */
+export function writePropertyOver(input, encodeNode) {
+    const value = captureDocumentValue(input.value, encodeNode);
+    if (value === undefined)
+        return { issue: "value type is not expressible in the document yet" };
+    const base = captureDocumentValue(input.previousValue, encodeNode);
+    if (!input.alwaysWrite && base !== undefined && JSON.stringify(base) === JSON.stringify(value)) {
+        return { reverted: { target: input.target, value: base } };
+    }
+    return { over: { target: input.target, value }, sequence: input.sequence ?? 0 };
+}
+export function isDocumentReferenceValue(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    if (typeof candidate.ref !== "string" || Object.keys(candidate).some(key => key !== "ref" && key !== "address"))
+        return false;
+    const address = candidate.address;
+    return address === undefined || (!!address && typeof address === "object" && !Array.isArray(address)
+        && Object.entries(address).every(([key, entry]) => ["id", "anchor", "type", "name", "path"].includes(key) && typeof entry === "string"));
+}
+export function captureDocumentValue(value, encodeNode) {
+    if (value === null)
+        return null;
+    if (isDocumentReferenceValue(value))
+        return { ref: value.ref, ...(value.address ? { address: { ...value.address } } : {}) };
+    switch (typeof value) {
+        case "number": return Number.isFinite(value) ? value : undefined;
+        case "string":
+        case "boolean":
+            return value;
+        case "object": {
+            // scene-object values (object slots) → NODE REFERENCES ({ref, address?});
+            // unattributable objects fall through to undefined = "not expressible"
+            if (value.isObject3D === true) {
+                return encodeNode?.(value);
+            }
+            const toArray = value.toArray;
+            if (typeof toArray === "function") {
+                const array = value.toArray();
+                if (Array.isArray(array)) {
+                    // three value types are numeric arrays: Vector[234]/Quaternion/Color
+                    // ([x,y,z(,w)]). Euler trails a string `order` — take the leading
+                    // numeric run; the evaluator's Euler.fromArray([x,y,z]) keeps the
+                    // node's own order. Reject anything with more than one trailing
+                    // non-number (not a known value type).
+                    const nums = [];
+                    for (const v of array) {
+                        if (typeof v === "number" && Number.isFinite(v))
+                            nums.push(v);
+                        else
+                            break;
+                    }
+                    if (nums.length > 0 && (nums.length === array.length || (nums.length === array.length - 1 && typeof array[array.length - 1] === "string")))
+                        return nums;
+                }
+            }
+            if (Array.isArray(value) && value.every(v => (typeof v === "number" && Number.isFinite(v)) || typeof v === "string" || typeof v === "boolean")) {
+                return [...value];
+            }
+            return undefined;
+        }
+        default:
+            return undefined;
+    }
+}
+export function documentOverKey(over) {
+    const t = over.target;
+    const addressKey = t.address?.id ?? t.address?.path ?? t.address?.name ?? "";
+    return `${t.ref ?? ""}::${addressKey}::${t.path ?? ""}`;
+}
+/**
+ * Merge base-document overs with freshly captured ones: a new over SUPERSEDES a base
+ * over on the same target (the user re-edited it); base overs whose reference is gone
+ * are dropped; everything else is preserved.
+ */
+export function mergeDocumentOvers(baseOvers, newOvers, liveRefs, contentRefIds, alwaysSuperseded, skipped) {
+    const superseded = new Set(newOvers.map(documentOverKey));
+    const result = [];
+    for (const over of baseOvers) {
+        // parent overs of the REGENERATED classes never merge back (re-derived
+        // live every save): address-less = reference roots; addressed on a CONTENT
+        // ref = content children. Addressed parent overs on OTHER refs are
+        // ops-recorded asset moves — they PERSIST across sessions and supersede
+        // by key on re-move.
+        if (over.target.path === "parent" && (!over.target.address || (over.target.ref !== undefined && contentRefIds.has(over.target.ref))))
+            continue;
+        if (over.target.ref && !liveRefs.has(over.target.ref)) {
+            // reference removed — the over dies with it. EXPECTED after a reference
+            // delete, but SURFACED regardless ("Save Project never drops an edit
+            // silently"): an unexpected entry here is the symptom of an attribution
+            // bug (wrong ref id), and silence cost a debugging session once
+            // (plans/project-format-v0.md item 7b).
+            skipped?.push(`over ${over.target.path ?? "?"} on reference "${over.target.ref}" — reference no longer exists, over dropped`);
+            continue;
+        }
+        const key = documentOverKey(over);
+        if (superseded.has(key))
+            continue; // re-edited below
+        if (alwaysSuperseded?.has(key))
+            continue; // rebuilt-from-live paths (placement)
+        result.push(over);
+    }
+    result.push(...newOvers);
+    return result;
+}

package/dist/id.d.ts

@@ -9,6 +9,8 @@ import type { GraphNode } from "./address.js";
 /** 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";
+/** Stable instance identity, preserving the namespace used by Engine duplication. */
+export declare function deriveInstanceId(scope: string, originalId: string): string;
 /**
  * The name an id is derived FROM: the anchor marker removed (if any) and space/underscore
  * runs collapsed.

package/dist/id.js

@@ -11,6 +11,10 @@ import { randomUuid, uuidv5 } from "./uuid.js";
  * `userData` for scene objects (exports copy one into the other). */
 export const NEEDLE_ID_KEY = "needle-id";
 // #region Derivation
+/** Stable instance identity, preserving the namespace used by Engine duplication. */
+export function deriveInstanceId(scope, originalId) {
+    return uuidv5(`${scope}:${originalId}`, "eff8ba80-635d-11ec-90d6-0242ac120003");
+}
 /**
  * The name an id is derived FROM: the anchor marker removed (if any) and space/underscore
  * runs collapsed.

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 export { ANCHOR_MARKER, ANCHOR_MARKERS, parseAnchor, parseAnchorValue, type ParsedAnchor } from "./anchor.js";
-export { computeElementId, ensureIds, ensureNodeId, getElementId, getNodeId, NEEDLE_ID_KEY, occurrenceOfName, shedNodeIdentity, type EnsureIdsOptions, type EnsureIdsResult, type ShedIdentityOptions, } from "./id.js";
+export { computeElementId, deriveInstanceId, 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";
+export { attachNeedleIdsToLoadedGltf, type GltfAssociation, type AttachNeedleIdsResult } from "./loadedGltf.js";

package/dist/index.js

@@ -1,7 +1,8 @@
 export { ANCHOR_MARKER, ANCHOR_MARKERS, parseAnchor, parseAnchorValue } from "./anchor.js";
-export { computeElementId, ensureIds, ensureNodeId, getElementId, getNodeId, NEEDLE_ID_KEY, occurrenceOfName, shedNodeIdentity, } from "./id.js";
+export { computeElementId, deriveInstanceId, 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";
+export { attachNeedleIdsToLoadedGltf } from "./loadedGltf.js";

package/dist/loadedGltf.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Eager-compute half of the persistent-id contract:
+ * ids are computed at LOAD time against the pristine glTF JSON — the deterministic inputs
+ * (original names and their order) only exist pristinely then — and attached to the LIVE
+ * objects' userData. The source file is not touched; persistence happens on save, where
+ * the exporter writes userData back into extras.
+ *
+ * Already-stamped assets carry ids in extras (which the loader copies to userData); those
+ * are respected and always win over recomputation.
+ */
+/** subset of three GLTFLoader's `parser.associations` values that we consume */
+export type GltfAssociation = {
+    nodes?: number;
+    materials?: number;
+    textures?: number;
+    cameras?: number;
+};
+type UserDataHost = {
+    userData?: Record<string, unknown>;
+};
+export type AttachNeedleIdsResult = {
+    /** how many live objects received an id (already-stamped userData is left untouched) */
+    attached: number;
+};
+/**
+ * Attach needle-ids to the live objects of a loaded glTF.
+ * @param json the PRISTINE parsed glTF JSON (as read from the file, before any mutation)
+ * @param associations three GLTFLoader `parser.associations` (live object → element indices)
+ * @param scenes loaded scene objects, ordered like `json.scenes`
+ */
+export declare function attachNeedleIdsToLoadedGltf(json: Record<string, unknown>, associations: ReadonlyMap<object, GltfAssociation | undefined> | null | undefined, scenes?: readonly (UserDataHost | null | undefined)[] | null): AttachNeedleIdsResult;
+export {};

package/dist/loadedGltf.js

@@ -0,0 +1,62 @@
+import { computeElementId, getElementId, NEEDLE_ID_KEY, occurrenceOfName } from "./id.js";
+/**
+ * association key → (glTF collection, element type) — in precedence order: the scene-graph
+ * identity (node) wins when one live object carries several associations (e.g. a Mesh
+ * created for a single-use glTF node). glTF `mesh` elements are deliberately NOT attached:
+ * they are shared data, and stamping a scene object with a mesh id would alias two
+ * identities (a mesh used by two nodes would give both objects the same id).
+ */
+const ASSOCIATION_MAPPING = [
+    ["nodes", "node"],
+    ["materials", "material"],
+    ["textures", "texture"],
+    ["cameras", "camera"],
+];
+/**
+ * Attach needle-ids to the live objects of a loaded glTF.
+ * @param json the PRISTINE parsed glTF JSON (as read from the file, before any mutation)
+ * @param associations three GLTFLoader `parser.associations` (live object → element indices)
+ * @param scenes loaded scene objects, ordered like `json.scenes`
+ */
+export function attachNeedleIdsToLoadedGltf(json, associations, scenes) {
+    let attached = 0;
+    const attach = (target, type, collection, index) => {
+        const userData = target.userData;
+        if (!userData || typeof userData !== "object")
+            return;
+        if (typeof userData[NEEDLE_ID_KEY] === "string")
+            return; // loader copied extras, or already attached
+        const elements = json[collection];
+        if (!Array.isArray(elements))
+            return;
+        const element = elements[index];
+        if (!element || typeof element !== "object")
+            return;
+        // occurrence-of-name (not index) is the id input — computed from the pristine
+        // collection so ids match what any other tool stamps for this file
+        const id = getElementId(element) ?? computeElementId(type, element.name, occurrenceOfName(elements, index));
+        userData[NEEDLE_ID_KEY] = id;
+        attached++;
+    };
+    if (associations) {
+        for (const [object, association] of associations) {
+            if (!association || typeof object !== "object")
+                continue;
+            for (const [key, type] of ASSOCIATION_MAPPING) {
+                const index = association[key];
+                if (typeof index === "number") {
+                    attach(object, type, key, index);
+                    break; // precedence: first matching association identifies the object
+                }
+            }
+        }
+    }
+    if (scenes) {
+        for (let i = 0; i < scenes.length; i++) {
+            const scene = scenes[i];
+            if (scene)
+                attach(scene, "scene", "scenes", i);
+        }
+    }
+    return { attached };
+}

package/dist/resolve.js

@@ -1,5 +1,5 @@
 import { parseAnchorValue } from "./anchor.js";
-import { collectionKeyForType, splitPath } from "./address.js";
+import { collectionKeyForType, splitNodePath } from "./address.js";
 import { NEEDLE_ID_KEY } from "./id.js";
 import { STAMPED_COLLECTIONS } from "./gltf.js";
 /**
@@ -51,7 +51,7 @@ export function resolveInGltf(address, json, options) {
     if (byId)
         return byId;
     if (address.path !== undefined && (!address.type || address.type === "node")) {
-        const index = walkGltfNamePath(json, splitPath(address.path));
+        const index = walkGltfNamePath(json, splitNodePath(address.path));
         if (index !== null) {
             const nodes = json["nodes"];
             return { type: "node", index, element: nodes[index] };
@@ -94,8 +94,9 @@ export function resolveInGraph(address, root, options) {
         return byId;
     if (address.path !== undefined) {
         let current = root;
-        for (const segment of splitPath(address.path)) {
-            current = current.children?.find(c => (c.name ?? "") === segment) ?? null;
+        for (const segment of splitNodePath(address.path)) {
+            const matches = current.children?.filter(c => (c.name ?? "") === segment.name) ?? [];
+            current = segment.occurrence !== undefined ? matches[segment.occurrence] ?? null : matches.length === 1 ? matches[0] : null;
             if (!current)
                 break;
         }
@@ -149,7 +150,7 @@ export function resolveInCollection(address, elements, options) {
  * path still matches. Callers decide thresholds and whether to re-anchor.
  */
 export function reconcileInGraph(address, root) {
-    const addressSegments = address.path !== undefined ? splitPath(address.path) : null;
+    const addressSegments = address.path !== undefined ? splitNodePath(address.path).map(segment => segment.name) : null;
     if (!address.name && !addressSegments?.length)
         return [];
     const targetName = address.name ?? addressSegments[addressSegments.length - 1];
@@ -208,7 +209,8 @@ function walkGltfNamePath(json, segments) {
     let candidates = scenes.flatMap(s => (Array.isArray(s?.nodes) ? s.nodes : []));
     let match = null;
     for (const segment of segments) {
-        match = candidates.find(i => ((nodes[i]?.name ?? "") === segment)) ?? null;
+        const matches = [...new Set(candidates)].filter(i => (nodes[i]?.name ?? "") === segment.name);
+        match = segment.occurrence !== undefined ? matches[segment.occurrence] ?? null : matches.length === 1 ? matches[0] : null;
         if (match === null)
             return null;
         const children = nodes[match]?.children;

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "@needle-tools/addressing",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "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",
   "types": "./src/index.ts",
   "exports": {
+    "./document/schema.json": "./src/document/schema.json",
+    "./document": {
+      "types": "./src/document/index.ts",
+      "node": "./dist/document/index.js",
+      "default": "./src/document/index.ts"
+    },
     ".": {
       "types": "./src/index.ts",
       "node": "./dist/index.js",
@@ -28,6 +34,8 @@
     "url": "https://needle.tools"
   },
   "devDependencies": {
+    "three": "^0.185.0",
+    "@types/three": "^0.185.0",
     "typescript": "^5.6.0",
     "vitest": "^3.0.0"
   },

package/src/address.ts

@@ -26,6 +26,7 @@ export type NeedleAddress = {
      * {@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".
+     * A `~2n` suffix selects the zero-based occurrence among same-named siblings.
      */
     path?: string;
 };
@@ -82,7 +83,7 @@ export function createGltfElementAddress(json: GltfJson, type: StampedElementTyp
     if (name) address.name = name;
     if (type === "node") {
         const segments = gltfNodeNamePath(json, index);
-        if (segments) address.path = joinPath(segments);
+        if (segments) address.path = segments.join("/");
     }
     return address;
 }
@@ -99,10 +100,31 @@ export function createObjectAddress(root: GraphNode, target: GraphNode): NeedleA
     if (anchor) address.anchor = anchor;
     // empty name dropped — see createGltfElementAddress; path segments stay verbatim
     if (target.name) address.name = target.name;
-    address.path = joinPath(nodes.map(n => n.name ?? ""));
+    let parent = root;
+    address.path = nodes.map(node => {
+        const siblings = parent.children ?? [];
+        parent = node;
+        return nodePathSegment(node.name ?? "", siblings, node);
+    }).join("/");
     return address;
 }
 
+/** `~2n` selects a same-named sibling; literal tildes were already escaped as `~0`. */
+function nodePathSegment(name: string, siblings: readonly GraphNode[], node: GraphNode): string {
+    const matches = siblings.filter(sibling => (sibling.name ?? "") === name);
+    const escaped = encodePathSegment(name);
+    return matches.length > 1 ? `${escaped}~2${matches.indexOf(node)}` : escaped;
+}
+
+export function splitNodePath(path: string): Array<{ name: string; occurrence?: number }> {
+    return path.split("/").map(segment => {
+        const qualifier = /~2(0|[1-9][0-9]*)$/.exec(segment);
+        return qualifier
+            ? { name: decodePathSegment(segment.slice(0, qualifier.index)), occurrence: Number(qualifier[1]) }
+            : { name: decodePathSegment(segment) };
+    });
+}
+
 export function collectionKeyForType(type: string): string {
     // glTF collection keys are the pluralized type names; only "mesh" is irregular
     return type === "mesh" ? "meshes" : `${type}s`;
@@ -123,7 +145,10 @@ function gltfNodeNamePath(json: GltfJson, nodeIndex: number): string[] | null {
     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 : "");
+        const parent = parents.get(current);
+        const siblingIndices: number[] = parent !== undefined ? nodes[parent]?.children ?? []
+            : [...new Set((Array.isArray(json.scenes) ? json.scenes : []).flatMap(scene => scene.nodes ?? []))];
+        path.unshift(nodePathSegment(typeof nodes[current]?.name === "string" ? nodes[current].name : "", siblingIndices.map(i => nodes[i]), nodes[current]));
         current = parents.get(current);
     }
     return path;