@needle-tools/addressing 0.3.4 → 0.4.0

package/Readme.md

@@ -6,6 +6,62 @@ Persistent addressing for glTF assets and three.js scene graphs: deterministic
 Zero runtime dependencies, no three.js import (scene graphs are accessed structurally),
 usable in browsers, node, and workers.
 
+## Project documents
+
+`@needle-tools/addressing/document` exports the document types, evaluator,
+single-def/over application, optional inspection index, and schema validator.
+The JSON Schema is available at `@needle-tools/addressing/document/schema.json`.
+The document format is unchanged by this package split.
+
+The shared writer exports `writePropertyOver`, `captureDocumentValue`,
+`documentOverKey`, and `mergeDocumentOvers`. These encode property edits, retain
+addresses, remove net-undo edits, and merge saved overs. Hosts still supply node
+reference encoding, live-target checks, asset assembly, and component serialization.
+Non-finite numbers and unsupported values produce a writer issue instead of being
+silently changed by JSON serialization.
+
+`DocumentAssetAssembly` registers deduplicated asset sources and shared material
+or HDR entities in the writer's asset/reference tables. Material assignments reuse
+saved entity identities by source and material ID, even when asset keys change.
+Hosts supply the captured entity IDs and resolve asset ownership; the assembly
+contains no engine or editor dependencies.
+
+The evaluator accepts a `DocumentRuntime` host. It owns asset caching, reference
+placement, derived glTF IDs, target resolution, defs, property and parent overs,
+entity sharing, and issue reporting. The host supplies loading, object creation,
+cloning, and lifecycle scheduling. Needle Engine provides its own adapter;
+plain three.js can use the same evaluator:
+
+```ts
+import { Color, Object3D, Scene } from "three";
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { evaluateProjectDocument, type DocumentRuntime } from "@needle-tools/addressing/document";
+
+const scene = new Scene();
+const runtime: DocumentRuntime = {
+    scene,
+    renderer, // your existing renderer, for $renderer opinions
+    createNode: () => new Object3D(),
+    createColor: value => new Color().fromArray(value),
+    parse: (data, src) => new GLTFLoader().parseAsync(data, new URL(".", new URL(src, documentUrl)).href),
+    instantiate: node => (node as Object3D).clone(),
+    // Plain objects have no component lifecycle or template registrations.
+    parkTemplate() {},
+    activateInstance() {},
+    disposeTemplate() {},
+    schedule: work => work(),
+    loadEnvironment, // your existing HDR/PMREM loader: (url, options) => Promise<Texture | null>
+};
+const result = await evaluateProjectDocument(runtime, document, { baseUrl: documentUrl });
+await result.completed;
+```
+
+Supply `createDefContext` and the component access hooks if the host supports
+components. Without them, component defs are reported as unsupported; node defs
+and ordinary three.js properties still work. A skeletal or component-aware host
+must supply its matching clone implementation. The default addressing entry point
+does not import the document evaluator or any three.js runtime.
+
 ## Ids
 
 Every glTF root-collection element (nodes, scenes, animations, cameras, materials,
@@ -34,6 +90,12 @@ An address captures every fallback at creation time, while the target is known
 1. `id` — exact match (`extras` in glTF JSON, `userData` in live scene graphs)
 2. `anchor` — survives asset updates
 3. `path` — best-effort structural match
+
+Node paths qualify same-named siblings with `~2n` (zero-based occurrence):
+`Cube~21` names the second `Cube`. Literal tildes remain escaped as `~0`.
+Unqualified ambiguous paths fail to resolve rather than picking the first child.
+These paths assume the original sibling order; use authored anchors or persistent
+IDs when the source scene changes.
 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

@@ -23,6 +23,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;
 };
@@ -44,6 +45,10 @@ export type GraphNode = {
 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 splitNodePath(path: string): Array<{
+    name: string;
+    occurrence?: number;
+}>;
 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

@@ -45,7 +45,7 @@ export function createGltfElementAddress(json, type, index) {
     if (type === "node") {
         const segments = gltfNodeNamePath(json, index);
         if (segments)
-            address.path = joinPath(segments);
+            address.path = segments.join("/");
     }
     return address;
 }
@@ -64,9 +64,28 @@ export function createObjectAddress(root, target) {
     // 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, siblings, node) {
+    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) {
+    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) {
     // glTF collection keys are the pluralized type names; only "mesh" is irregular
     return type === "mesh" ? "meshes" : `${type}s`;
@@ -90,7 +109,10 @@ function gltfNodeNamePath(json, nodeIndex) {
         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 = 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;

package/dist/document/assets.d.ts

@@ -0,0 +1,27 @@
+import type { ProjectDocument, ProjectDocumentAsset, ProjectDocumentReference } from "./types.js";
+/** Asset keys and shared resource identities for one document assembly. */
+export declare class DocumentAssetAssembly {
+    private readonly assets;
+    private readonly references;
+    private readonly assetBySrc;
+    private readonly referenceById;
+    private readonly materialBySource;
+    private readonly baseMaterialBySource;
+    constructor(assets: Record<string, ProjectDocumentAsset>, references: ProjectDocumentReference[], base?: ProjectDocument | null);
+    addAsset(input: {
+        src: string;
+        name?: string;
+        kind: string;
+        identity?: {
+            id: string;
+            provider?: string;
+        };
+    }): string;
+    materialEntity(asset: string, material: {
+        id: string;
+        name?: string;
+    }, entityId: string): string;
+    environmentEntity(asset: string, entityId: string): string;
+    private addReference;
+    private materialKey;
+}

package/dist/document/assets.js

@@ -0,0 +1,75 @@
+/** Asset keys and shared resource identities for one document assembly. */
+export class DocumentAssetAssembly {
+    constructor(assets, references, base) {
+        this.assets = assets;
+        this.references = references;
+        this.assetBySrc = new Map();
+        this.referenceById = new Map();
+        this.materialBySource = new Map();
+        this.baseMaterialBySource = new Map();
+        for (const [key, asset] of Object.entries(assets))
+            this.assetBySrc.set(asset.src, key);
+        for (const reference of references) {
+            this.referenceById.set(reference.id, reference);
+            const key = this.materialKey(reference, assets);
+            if (key)
+                this.materialBySource.set(key, reference);
+        }
+        for (const reference of base?.references ?? []) {
+            const key = this.materialKey(reference, base?.assets ?? {});
+            if (key)
+                this.baseMaterialBySource.set(key, reference);
+        }
+    }
+    addAsset(input) {
+        const existing = this.assetBySrc.get(input.src);
+        if (existing !== undefined)
+            return existing;
+        const filename = input.src.split("?")[0].split("/").pop() || "material";
+        const dot = filename.lastIndexOf(".");
+        const stem = input.name || (dot > 0 ? filename.substring(0, dot) : filename);
+        let key = stem;
+        let n = 2;
+        while (key in this.assets)
+            key = `${stem}-${n++}`;
+        this.assets[key] = { src: input.src, kind: input.kind, ...(input.identity ? { asset: { ...input.identity } } : {}) };
+        this.assetBySrc.set(input.src, key);
+        return key;
+    }
+    materialEntity(asset, material, entityId) {
+        if (!this.assets[asset])
+            throw new Error(`Unknown document asset: ${asset}`);
+        const key = JSON.stringify([this.assets[asset].src, material.id]);
+        const existing = this.materialBySource.get(key);
+        if (existing)
+            return existing.id;
+        const base = this.baseMaterialBySource.get(key);
+        const reference = base ? { ...base, asset } : {
+            id: entityId, asset, address: { type: "material", id: material.id, ...(material.name ? { name: material.name } : {}) },
+        };
+        this.addReference(reference);
+        this.materialBySource.set(key, reference);
+        return reference.id;
+    }
+    environmentEntity(asset, entityId) {
+        if (!this.assets[asset])
+            throw new Error(`Unknown document asset: ${asset}`);
+        this.addReference({ id: entityId, asset, address: { type: "hdr" } });
+        return entityId;
+    }
+    addReference(reference) {
+        const existing = this.referenceById.get(reference.id);
+        if (existing) {
+            if (existing.asset !== reference.asset || existing.address?.type !== reference.address?.type || existing.address?.id !== reference.address?.id) {
+                throw new Error(`Document reference id '${reference.id}' already identifies another resource`);
+            }
+            return;
+        }
+        this.references.push(reference);
+        this.referenceById.set(reference.id, reference);
+    }
+    materialKey(reference, assets) {
+        return reference.address?.type === "material" && reference.address.id && assets[reference.asset]
+            ? JSON.stringify([assets[reference.asset].src, reference.address.id]) : null;
+    }
+}

package/dist/document/collectionSelector.d.ts

@@ -0,0 +1,9 @@
+export interface DocumentCollectionSelectorOptions {
+    matchesComponentType?(component: object, name: string): boolean;
+    matchesComponentGuid?(component: object, guid: string): boolean;
+    deriveComponentGuid?(referenceId: string, fileGuid: string): string;
+    referenceId?: string;
+    report?(message: string): void;
+}
+/** Resolve an index or field qualifier; ambiguous identities never select an arbitrary member. */
+export declare function resolveDocumentCollectionElement(collection: readonly unknown[], selector: string, options?: DocumentCollectionSelectorOptions): unknown;

package/dist/document/collectionSelector.js

@@ -0,0 +1,29 @@
+/** Resolve an index or field qualifier; ambiguous identities never select an arbitrary member. */
+export function resolveDocumentCollectionElement(collection, selector, options = {}) {
+    if (/^\d+$/.test(selector))
+        return collection[Number(selector)];
+    const qualifier = /^([A-Za-z_][A-Za-z0-9_-]*):([\s\S]*)$/.exec(selector);
+    if (!qualifier) {
+        options.report?.(`"${selector}" is neither an index nor a <field>:<value> qualifier`);
+        return undefined;
+    }
+    const [, field, value] = qualifier;
+    const elements = collection.filter((element) => element !== null && typeof element === "object");
+    let matches = elements.filter(element => {
+        if (field === "type")
+            return options.matchesComponentType?.(element, value) ?? element.constructor?.name === value;
+        if (field === "guid")
+            return options.matchesComponentGuid?.(element, value)
+                ?? (element.guid === value || element.needle_editor_guid === value);
+        return element[field] === value;
+    });
+    if (!matches.length && field === "guid" && options.referenceId && options.deriveComponentGuid) {
+        const derived = options.deriveComponentGuid(options.referenceId, value);
+        matches = elements.filter(element => element.guid === derived);
+    }
+    if (matches.length > 1) {
+        options.report?.(`"${selector}" matched ${matches.length} elements ? the document must name one unambiguously`);
+        return undefined;
+    }
+    return matches[0];
+}

package/dist/document/evaluate.d.ts

@@ -0,0 +1,72 @@
+import { type NeedleAddress } from "../index.js";
+import { type ProjectDocument, type ProjectDocumentTarget, type ProjectEvaluationIssue, type ProjectEvaluationResult, type EvaluateProjectDocumentOptions } from "./types.js";
+import type { DocumentNode as Object3D, DocumentModel as Model, DocumentRuntime as Context, DocumentDefContext as SerializationContext } from "./runtime.js";
+/** Shared asset/entity preparation; does not place nodes into the host scene. */
+export declare function createDocumentAssetLoader(context: Pick<Context, "parse" | "parkTemplate" | "loadEnvironment">, document: ProjectDocument, options: EvaluateProjectDocumentOptions | undefined, issue: (arc: ProjectEvaluationIssue["arc"], message: string) => void): {
+    loadParsedAsset: (assetId: string, arc?: ProjectEvaluationIssue["arc"]) => Promise<Model | null>;
+    entities: Map<string, Promise<object | null>>;
+};
+/**
+ * Evaluate a project document into the given context. One-shot; never throws for
+ * content issues (they are collected in the result), only for a non-document input.
+ *
+ * Order (plans/project-format-v0.md): load + place references (document order) →
+ * mounts → [pre-setup phase:] asset component deserialization (the engine's own
+ * queue, FIFO) → defs → overs. Resolution is scoped to the target reference's
+ * subtree; misses are reported and skipped (exact resolution only in v0).
+ */
+export declare function evaluateProjectDocument(context: Context, document: ProjectDocument, options?: EvaluateProjectDocumentOptions): Promise<ProjectEvaluationResult>;
+export declare function splitPath(path: string): string[];
+/**
+ * The serialization context ONE def application (or a whole document's worth)
+ * deserializes through: rooted at the COMPOSITION root so `{guid}` references in
+ * def data resolve across the whole composed result (cross-reference wiring).
+ * `baseUrl`: URL-string component fields (e.g. a tracked image's remote object) go
+ * through the EXISTING AssetReference.getOrCreate deserialization — it needs a
+ * source id to resolve document-relative urls against (no new loading path).
+ */
+export declare function createDefSerializationContext(context: Context, root: Object3D, baseUrl?: string): SerializationContext;
+/**
+ * Apply ONE def to the live composition — create/adopt the node, then
+ * instantiate/adopt its components. Exported as the single-arc primitive:
+ * document evaluation loops over it, and the op-bridge APPLICATOR applies a
+ * creation op's carried def through exactly this function (one implementation,
+ * plans/operation-bridge.md fixture 2).
+ */
+export declare function applyDef(def: NonNullable<ProjectDocument["defs"]>[number], root: Object3D, references: Map<string, Object3D>, issue: (arc: "def", message: string) => void, serializationContext: SerializationContext): void;
+/**
+ * The shared state a sequence of over applications rides — constructed once per
+ * document evaluation AND once per op-bridge apply session (the applicator,
+ * plans/operation-bridge.md fixture 2):
+ * - async entity chaining: entity-targeted overs and entity-ref values await the
+ *   entity's instantiation; overs touching the same entity keep their order among
+ *   themselves by chaining on the entity's tail promise. Non-async overs apply
+ *   synchronously (pre-awake); `settled()` awaits the async remainder.
+ * - deactivated subtrees ("active": false → removeFromParent), per scope ref:
+ *   materials are RESOURCES, not graph nodes — a material used only by a
+ *   deactivated mesh must stay addressable (doc order legally deactivates first
+ *   and patches after), so material resolution searches these detached roots too.
+ */
+export type OverApplyState = {
+    /** Bind original-scene addresses before any rename, removal or reparent changes their paths. */
+    sceneTargets?: ReadonlyMap<ProjectDocumentTarget, Object3D | null>;
+    readonly entities: Map<string, Promise<object | null>>;
+    readonly deactivatedRoots: Map<string | undefined, Object3D[]>;
+    chainOnEntity(refId: string, work: (entity: object | null) => void): void;
+    settled(): Promise<void>;
+};
+export declare function createOverApplyState(entities: Map<string, Promise<object | null>>): OverApplyState;
+/**
+ * Apply ONE over to the live composition — the single-arc primitive: document
+ * evaluation loops over it, and the op-bridge APPLICATOR applies a remote
+ * property/assign/deactivation op through exactly this function (one
+ * implementation, plans/operation-bridge.md fixture 2).
+ */
+export declare function applyOver(context: Context, over: NonNullable<ProjectDocument["overs"]>[number], root: Object3D, references: Map<string, Object3D>, state: OverApplyState, issue: (arc: "over", message: string) => void): void;
+/**
+ * Material entity resolution incl. MATERIAL-ONLY glbs (a promoted material
+ * library entry: materials but no scene/meshes). The loader never
+ * instantiates an unreferenced material, so a scene traversal finds nothing —
+ * pull the materials from the parser instead. Exported for tests.
+ */
+export declare function resolveMaterialEntity(model: Model, address: NeedleAddress): Promise<object | null>;