@needle-tools/addressing 0.3.4 → 0.4.0-1791982227.dramatic-tempura.8b3a85e

package/Readme.md

@@ -1,70 +1,151 @@
-# @needle-tools/addressing
-
-Persistent addressing for glTF assets and three.js scene graphs: deterministic
-`needle-id` computation, the `#needle` name-anchor scheme, and address resolution.
-
-Zero runtime dependencies, no three.js import (scene graphs are accessed structurally),
-usable in browsers, node, and workers.
-
-## Ids
-
-Every glTF root-collection element (nodes, scenes, animations, cameras, materials,
-meshes, skins, textures, images, samplers) can carry a UUID in `extras["needle-id"]`:
-
-- **Anchored** — the element name ends with `#needle` (case-insensitive): the id derives
-  only from the text before the marker → it **survives any content change** as long as
-  the name stays. Spaces and underscores in the value are treated as equal (loaders
-  sanitize node names), so `Door Frame #needle` and `Door_Frame_#needle` share one id.
-- **Unanchored**: the id derives from the element's type, name, and its occurrence among
-  same-named elements → uniquely named elements keep their ids across reorders and
-  content updates; duplicates disambiguate by position within their name group; unnamed
-  elements are positional.
-
-`ensureIds(gltfJson)` stamps a parsed glTF idempotently — existing ids are never
-overwritten, and any tool stamping the same element mints the same id.
-
-`ensureIds(gltfJson, { baseHash })` optionally salts unanchored ids with a caller-supplied
-identity (e.g. a stable asset id), scoping them to that identity.
-
-## Addresses
-
-An address captures every fallback at creation time, while the target is known —
-`{ id, anchor?, type?, name?, 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. `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.
-
-## API
-
-```ts
-import {
-    ensureIds, computeElementId, computeFileHash,         // write side
-    createGltfElementAddress, createObjectAddress,        // address records
-    resolveInGltf, resolveInGraph, reconcileInGraph,      // resolve side
-    parseAnchorValue, randomUuid, NEEDLE_ID_KEY,
-} from "@needle-tools/addressing";
-
-// stamp a parsed glTF (idempotent, never overwrites existing ids)
-const { fileHash, assigned } = ensureIds(gltfJson);
-
-// capture an address while the target is known
-const address = createObjectAddress(sceneRoot, targetObject);
-
-// later / elsewhere: resolve — or reconcile when the asset changed
-const hit = resolveInGraph(address, sceneRoot);
-const candidates = hit ? [] : reconcileInGraph(address, sceneRoot);
-```
-
-Out of scope by design: GLB container parsing (this package takes parsed JSON), file
-I/O, and any composition/override semantics.
-
-## Development
-
-```
-npm install
-npm test        # vitest — includes golden-fixture id tests
-npm run build   # tsc → dist/
-```
+# @needle-tools/addressing
+
+Persistent addressing for glTF assets and three.js scene graphs: deterministic
+`needle-id` computation, the `#needle` name-anchor scheme, and address resolution.
+
+Zero runtime dependencies, no three.js import (scene graphs are accessed structurally),
+usable in browsers, node, and workers.
+
+## 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),
+    clone: 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,
+meshes, skins, textures, images, samplers) can carry a UUID in `extras["needle-id"]`:
+
+- **Anchored** — the element name ends with `#needle` (case-insensitive): the id derives
+  only from the text before the marker → it **survives any content change** as long as
+  the name stays. Spaces and underscores in the value are treated as equal (loaders
+  sanitize node names), so `Door Frame #needle` and `Door_Frame_#needle` share one id.
+- **Unanchored**: the id derives from the element's type, name, and its occurrence among
+  same-named elements → uniquely named elements keep their ids across reorders and
+  content updates; duplicates disambiguate by position within their name group; unnamed
+  elements are positional.
+
+`ensureIds(gltfJson)` stamps a parsed glTF idempotently — existing ids are never
+overwritten, and any tool stamping the same element mints the same id.
+
+`ensureIds(gltfJson, { baseHash })` optionally salts unanchored ids with a caller-supplied
+identity (e.g. a stable asset id), scoping them to that identity.
+
+## Addresses
+
+An address captures every fallback at creation time, while the target is known —
+`{ id, anchor?, type?, name?, 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. `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.
+
+## API
+
+```ts
+import {
+    ensureIds, computeElementId, computeFileHash,         // write side
+    createGltfElementAddress, createObjectAddress,        // address records
+    resolveInGltf, resolveInGraph, reconcileInGraph,      // resolve side
+    parseAnchorValue, randomUuid, NEEDLE_ID_KEY,
+} from "@needle-tools/addressing";
+
+// stamp a parsed glTF (idempotent, never overwrites existing ids)
+const { fileHash, assigned } = ensureIds(gltfJson);
+
+// capture an address while the target is known
+const address = createObjectAddress(sceneRoot, targetObject);
+
+// later / elsewhere: resolve — or reconcile when the asset changed
+const hit = resolveInGraph(address, sceneRoot);
+const candidates = hit ? [] : reconcileInGraph(address, sceneRoot);
+```
+
+GLB parsing and file I/O belong to the host. The `/document` entry point provides
+document composition through a host-supplied `DocumentRuntime`.
+
+## Loaded documents
+
+```ts
+import { loadProjectDocument } from '@needle-tools/addressing/document';
+
+const loaded = await loadProjectDocument(runtime, documentJson, { baseUrl: documentUrl });
+const root = loaded.resolve({ ref: 'placed-reference-id' });
+const target = root && loaded.addressOf(root);
+```
+
+The result contains a frozen copy of the document JSON, the scene `root`, placed
+`references`, per-reference `models`, evaluation `issues`, and `resolve`/`addressOf`.
+It waits for scheduled composition and address indexing before returning. Reference
+IDs distinguish separate placements of the same asset. Resolution uses the existing
+document inspection index, including reference roots and reparented objects.
+
+The host owns fetching, cancellation, resource disposal, rendering, and script
+lifecycle. No editor or renderer implementation is imported by this API.
+
+## Development
+
+```
+npm install
+npm test        # vitest — includes golden-fixture id tests
+npm run build   # tsc → dist/
+```

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,86 @@
+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, DocumentExtensionProvider } from "./runtime.js";
+import type { ProjectDocumentDef } from './types.js';
+/** Controls reapplying component data to a scene that is already loaded. */
+export interface ApplyDefOptions {
+    /** Restore components without creating nodes or resetting their transforms. */
+    readonly componentsOnly?: boolean;
+    /** Resolve addresses against the current scene at the moment they are used. */
+    readonly resolveTarget?: (target: ProjectDocumentTarget) => Object3D | null;
+}
+/** Finds the existing node that owns a definition's components without creating or editing it. */
+export declare function resolveDefComponentHost(def: ProjectDocumentDef, resolveTarget: NonNullable<ApplyDefOptions['resolveTarget']>): Object3D | null;
+/** 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, providers?: ProjectDocument["extensions"], options?: ApplyDefOptions): 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 = {
+    /** Recovery resolves against the already-open document rather than rebuilding its references. */
+    resolveValueReference?: (target: ProjectDocumentTarget) => Object3D | null;
+    /** Decoders for versioned extension values; missing readers never raw-assign payloads. */
+    extensions?: ReadonlyMap<string, DocumentExtensionProvider>;
+    /** 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>;