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

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-1791982227.dramatic-tempura.8b3a85e",
   "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"
   },
@@ -39,4 +47,4 @@
     "type": "git",
     "url": "https://github.com/needle-tools/addressing.git"
   }
-}
+}

package/src/address.ts

@@ -1,144 +1,169 @@
-import { parseAnchorValue } from "./anchor.js";
-import { getElementId, NEEDLE_ID_KEY } from "./id.js";
-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) → `path`
- * (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. ONE path syntax everywhere (2026-08-03): `/`-separated segments
-     * with JSON-Pointer escaping (`~0` = `~`, `~1` = `/`) — see {@link joinPath} /
-     * {@link splitPath}. Empty SEGMENTS are load-bearing (positional walk over
-     * unnamed nodes), so `""` is a valid one-segment path — test `!== undefined`,
-     * never truthiness. ABSENT means "no path rung".
-     */
-    path?: string;
-};
-
-// #region path segment syntax
-// The one path syntax of the project format (target.path uses the same rules):
-// "/" separates segments; a literal "~" in a name is written "~0", a literal "/"
-// is written "~1" (JSON-Pointer, RFC 6901). Escape order matters on decode.
-
-/** escape one segment for embedding in a path string */
-export function encodePathSegment(name: string): string {
-    return name.replace(/~/g, "~0").replace(/\//g, "~1");
-}
-
-/** decode one path segment back to the literal name */
-export function decodePathSegment(segment: string): string {
-    return segment.replace(/~1/g, "/").replace(/~0/g, "~");
-}
-
-/** join literal segment names into an escaped path string */
-export function joinPath(segments: readonly string[]): string {
-    return segments.map(encodePathSegment).join("/");
-}
-
-/** split an escaped path string into literal segment names ("" → one empty segment) */
-export function splitPath(path: string): string[] {
-    return path.split("/").map(decodePathSegment);
-}
-
-/** 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. `path` only applies to nodes. */
-export function createGltfElementAddress(json: GltfJson, type: StampedElementType | string, index: number): NeedleAddress | null {
-    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: NeedleAddress = { 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 →
-    // path) and reconciliation falls back to the last path segment ("" again).
-    // NOTE: empty path SEGMENTS are load-bearing (positional child-walk) — only the
-    // standalone `name` field is dropped when empty.
-    if (name) address.name = name;
-    if (type === "node") {
-        const segments = gltfNodeNamePath(json, index);
-        if (segments) address.path = joinPath(segments);
-    }
-    return address;
-}
-
-/** Build an address for a live scene-graph object under `root`. */
-export function createObjectAddress(root: GraphNode, target: GraphNode): NeedleAddress | null {
-    const nodes = findPath(root, target);
-    if (!nodes || nodes.length === 0) return null; // the root itself has no path — address it by ref alone
-
-    const address: NeedleAddress = { 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; path segments stay verbatim
-    if (target.name) address.name = target.name;
-    address.path = joinPath(nodes.map(n => n.name ?? ""));
-    return address;
-}
-
-export function collectionKeyForType(type: string): string {
-    // 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: GltfJson, nodeIndex: number): string[] | null {
-    const nodes = json["nodes"];
-    if (!Array.isArray(nodes)) return null;
-    const parents = new Map<number, number>();
-    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: string[] = [];
-    let current: number | undefined = nodeIndex;
-    const seen = new Set<number>();
-    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: GraphNode, target: GraphNode): GraphNode[] | null {
-    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;
-}
+import { parseAnchorValue } from "./anchor.js";
+import { getElementId, NEEDLE_ID_KEY } from "./id.js";
+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) → `path`
+ * (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. ONE path syntax everywhere (2026-08-03): `/`-separated segments
+     * with JSON-Pointer escaping (`~0` = `~`, `~1` = `/`) — see {@link joinPath} /
+     * {@link splitPath}. Empty SEGMENTS are load-bearing (positional walk over
+     * unnamed nodes), so `""` is a valid one-segment path — test `!== undefined`,
+     * never truthiness. ABSENT means "no path rung".
+     * A `~2n` suffix selects the zero-based occurrence among same-named siblings.
+     */
+    path?: string;
+};
+
+// #region path segment syntax
+// The one path syntax of the project format (target.path uses the same rules):
+// "/" separates segments; a literal "~" in a name is written "~0", a literal "/"
+// is written "~1" (JSON-Pointer, RFC 6901). Escape order matters on decode.
+
+/** escape one segment for embedding in a path string */
+export function encodePathSegment(name: string): string {
+    return name.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+
+/** decode one path segment back to the literal name */
+export function decodePathSegment(segment: string): string {
+    return segment.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+/** join literal segment names into an escaped path string */
+export function joinPath(segments: readonly string[]): string {
+    return segments.map(encodePathSegment).join("/");
+}
+
+/** split an escaped path string into literal segment names ("" → one empty segment) */
+export function splitPath(path: string): string[] {
+    return path.split("/").map(decodePathSegment);
+}
+
+/** 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. `path` only applies to nodes. */
+export function createGltfElementAddress(json: GltfJson, type: StampedElementType | string, index: number): NeedleAddress | null {
+    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: NeedleAddress = { 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 →
+    // path) and reconciliation falls back to the last path segment ("" again).
+    // NOTE: empty path SEGMENTS are load-bearing (positional child-walk) — only the
+    // standalone `name` field is dropped when empty.
+    if (name) address.name = name;
+    if (type === "node") {
+        const segments = gltfNodeNamePath(json, index);
+        if (segments) address.path = segments.join("/");
+    }
+    return address;
+}
+
+/** Build an address for a live scene-graph object under `root`. */
+export function createObjectAddress(root: GraphNode, target: GraphNode): NeedleAddress | null {
+    const nodes = findPath(root, target);
+    if (!nodes || nodes.length === 0) return null; // the root itself has no path — address it by ref alone
+
+    const address: NeedleAddress = { 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; path segments stay verbatim
+    if (target.name) address.name = target.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`;
+}
+
+/** names from root (exclusive) to the node at `nodeIndex` (inclusive), via the scene tree */
+function gltfNodeNamePath(json: GltfJson, nodeIndex: number): string[] | null {
+    const nodes = json["nodes"];
+    if (!Array.isArray(nodes)) return null;
+    const parents = new Map<number, number>();
+    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: string[] = [];
+    let current: number | undefined = nodeIndex;
+    const seen = new Set<number>();
+    while (current !== undefined) {
+        if (seen.has(current)) return null; // malformed (cyclic) input
+        seen.add(current);
+        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;
+}
+
+/** path from root (exclusive) to target (inclusive), or null if target is not under root */
+export function findPath(root: GraphNode, target: GraphNode): GraphNode[] | null {
+    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/src/anchor.ts

@@ -1,71 +1,71 @@
-/**
- * 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: readonly string[] = [ANCHOR_MARKER];
-
-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 function parseAnchor(rawName: string | null | undefined): ParsedAnchor | null {
-    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: string): string {
-    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: string | null | undefined): string | null {
-    return parseAnchor(rawName)?.value ?? null;
-}
-
-function byLengthDescending(markers: readonly string[]): readonly string[] {
-    return markers.length > 1 ? [...markers].sort((a, b) => b.length - a.length) : markers;
-}
+/**
+ * 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: readonly string[] = [ANCHOR_MARKER];
+
+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 function parseAnchor(rawName: string | null | undefined): ParsedAnchor | null {
+    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: string): string {
+    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: string | null | undefined): string | null {
+    return parseAnchor(rawName)?.value ?? null;
+}
+
+function byLengthDescending(markers: readonly string[]): readonly string[] {
+    return markers.length > 1 ? [...markers].sort((a, b) => b.length - a.length) : markers;
+}

package/src/document/assets.ts

@@ -0,0 +1,77 @@
+import type { ProjectDocument, ProjectDocumentAsset, ProjectDocumentReference } from "./types.js";
+
+/** Asset keys and shared resource identities for one document assembly. */
+export class DocumentAssetAssembly {
+    private readonly assetBySrc = new Map<string, string>();
+    private readonly referenceById = new Map<string, ProjectDocumentReference>();
+    private readonly materialBySource = new Map<string, ProjectDocumentReference>();
+    private readonly baseMaterialBySource = new Map<string, ProjectDocumentReference>();
+
+    constructor(
+        private readonly assets: Record<string, ProjectDocumentAsset>,
+        private readonly references: ProjectDocumentReference[],
+        base?: ProjectDocument | null,
+    ) {
+        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: { src: string; name?: string; kind: string; identity?: { id: string; provider?: string } }): string {
+        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: string, material: { id: string; name?: string }, entityId: string): string {
+        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: ProjectDocumentReference = 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: string, entityId: string): string {
+        if (!this.assets[asset]) throw new Error(`Unknown document asset: ${asset}`);
+        this.addReference({ id: entityId, asset, address: { type: "hdr" } });
+        return entityId;
+    }
+
+    private addReference(reference: ProjectDocumentReference): void {
+        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);
+    }
+
+    private materialKey(reference: ProjectDocumentReference, assets: Record<string, ProjectDocumentAsset>): string | null {
+        return reference.address?.type === "material" && reference.address.id && assets[reference.asset]
+            ? JSON.stringify([assets[reference.asset].src, reference.address.id]) : null;
+    }
+}