@needle-tools/addressing 0.3.4 → 0.4.0

package/src/document/types.ts

@@ -0,0 +1,249 @@
+import type { NeedleAddress } from "../address.js";
+import type { DocumentNode, DocumentModel } from "./runtime.js";
+
+/** the version discriminator key every project document must carry */
+export const PROJECT_DOCUMENT_KEY = "needle:project";
+
+export type ProjectDocumentAsset = {
+    /** where the asset lives — resolved against `EvaluateProjectDocumentOptions.baseUrl` */
+    src: string;
+    /**
+     * Optional PROVIDER IDENTITY for assets whose resources (textures, buffers) live at
+     * provider-specific urls that `src` alone can't reach (e.g. PolyHaven). The host recovers
+     * the provider's resolver from this identity at load time (see
+     * `EvaluateProjectDocumentOptions.resolveAssetUrl`). Self-contained assets omit it and
+     * load by `src`. The engine ignores it; only the host (editor) reads it.
+     */
+    asset?: { id: string; provider?: string };
+    /**
+     * Optional SEMANTIC KIND, decided at USE time by the writer ("model", "material",
+     * "hdr", "texture", "image", "video", "audio", "code", "text") — the same file can
+     * be a texture on a material slot or a plain image in UI, and downstream
+     * processing (compression at publish) follows the use, not the extension. The
+     * engine ignores it; only hosts/tooling read it.
+     */
+    kind?: string;
+    /**
+     * INFORMATIONAL: the server `ETag` observed when this document captured the
+     * asset — lets a future reader detect "the upstream file changed since".
+     * Never used for loading decisions; the engine ignores it.
+     */
+    etag?: string;
+};
+
+export type ProjectDocumentReference = {
+    /** project-local id of this reference — the resolution scope (or entity handle) for targets */
+    id: string;
+    /** key into the document's `assets` map */
+    asset: string;
+    /**
+     * ELEMENT REFERENCE discriminator: when present, this reference instantiates the
+     * addressed element INSIDE the asset (e.g. a material) into the composition's ENTITY
+     * POOL instead of placing a scene subtree. Entity references are first-class composed
+     * entities: overs can target them (`{ ref: <id>, path: "map/repeat" }`) and values can
+     * point at them (`{ ref: <id> }` — e.g. a mesh's material assignment). N consumers of
+     * the same entity share ONE runtime instance by construction (USD: a Material-prim
+     * reference; assignment ≈ material:binding).
+     */
+    address?: NeedleAddress;
+    /** @deprecated (2026-08-03, read-only shim — remove soon) replaced by parent OVERS
+     * (`{ target: { ref, path: "parent" }, value: { ref | "$scene", address?, index? } }`)
+     * days after shipping; only unreleased documents from that week carry this field.
+     * The writer no longer emits it; the evaluator still honors it at placement. */
+    parent?: { ref: string; address?: NeedleAddress };
+};
+
+/** A host-owned root that document opinions compose onto instead of instantiating. */
+export type ProjectDocumentBinding = {
+    /** Document-local reference used by targets. `$`-prefixed ids are reserved. */
+    id: string;
+    /** The kind of host root required by this document. */
+    kind: "scene";
+    /** Stable structural identity used by the host to match this root before applying edits. */
+    signature: string;
+    /** Informational label for diagnostics only; never used as identity. */
+    name?: string;
+    /** Existing asset-reference ids whose instances belong to this host root. */
+    references?: string[];
+};
+
+export type ProjectDocumentTarget = {
+    /** which placed reference the address resolves WITHIN; omitted → the composition root */
+    ref?: string;
+    /** fat address of the element inside the reference (needle-id / anchor / path) */
+    address?: NeedleAddress;
+    /**
+     * Property path within the resolved element, "/"-separated.
+     *
+     * A segment landing on a COLLECTION may be a `<field>:<value>` qualifier instead of an
+     * index — `components/type:DragControls/enabled`, `components/guid:6f1f…/enabled` —
+     * so a document never depends on array order (`userData.components` reorders whenever
+     * a component is added or removed). A bare numeric segment on an array is still an
+     * index, but it is now an explicit opt-in rather than the only option.
+     * `components` is a synthesized segment on a node: the live layout
+     * (`userData.components`) stays an implementation detail.
+     *
+     * Reserved LAST segment: `active` — with `value: false` it removes whatever the rest
+     * of the path resolved to (the node itself, or a component) from the composed result.
+     */
+    path?: string;
+};
+
+export type ProjectDocumentDef = {
+    target: ProjectDocumentTarget;
+    /**
+     * When present, the def CREATES a new node (USD-proper: def defines prims) under the
+     * resolved target (composition root when the target is empty) and the components
+     * apply to IT — e.g. the runtime start camera. Without `create`, components apply to
+     * the resolved existing node.
+     */
+    create?: {
+        id?: string;
+        name?: string;
+        position?: number[];
+        quaternion?: number[];
+        scale?: number[];
+        /** Recreate a hierarchy duplicate from its stable source and seed. */
+        copy?: {
+            source: ProjectDocumentTarget;
+            seed: string;
+            reference?: boolean;
+        } & ({ batch: string; index: number } | { batch?: never; index?: never });
+    };
+    /** VERBATIM NEEDLE_components wire entries ({ name, guid, ...fields }) */
+    components?: Array<{ name: string } & Record<string, unknown>>;
+};
+
+export type ProjectDocumentOver = {
+    target: ProjectDocumentTarget;
+    value: unknown;
+};
+
+export type ProjectDocument = {
+    [PROJECT_DOCUMENT_KEY]: string;
+    /** layer metadata (USD's "layer metadata" concept — e.g. `name`); free-form */
+    metadata?: Record<string, unknown>;
+    /** named remote origins for `remote://<name>/<path>` srcs — the scheme
+     * routes, the AUTHORITY names the remote, this table supplies the base.
+     * Resolved per DOCUMENT (a nested document resolves with ITS table), so
+     * the document works wherever it travels. Semantics mirror the editor's
+     * remoteSrc.ts — keep the two in sync. */
+    remotes?: Record<string, string>;
+    assets?: Record<string, ProjectDocumentAsset>;
+    /** Required host-owned roots. The host resolves these before evaluation. */
+    bindings?: ProjectDocumentBinding[];
+    references?: ProjectDocumentReference[];
+    defs?: ProjectDocumentDef[];
+    overs?: ProjectDocumentOver[];
+    /** unknown arcs are ignored by evaluation and must be preserved by writers */
+    [arc: string]: unknown;
+};
+
+const REMOTE_SRC_SCHEME = "remote://";
+
+/**
+ * Resolve a `remote://name/path` src via the document's remotes table
+ * (`overrides` win for known names — the host's per-environment repoint, e.g.
+ * the editor's dev proxy). Non-remote srcs pass through. An UNKNOWN remote
+ * name resolves to null — the caller reports it; guessing a base would load
+ * the wrong bytes silently. MIRRORS the editor's remoteSrc.ts resolveRemoteSrc.
+ */
+export function resolveDocumentRemoteSrc(src: string, remotes: Record<string, string> | undefined, overrides?: Record<string, string>): string | null {
+    if (!src.startsWith(REMOTE_SRC_SCHEME)) return src;
+    const rest = src.substring(REMOTE_SRC_SCHEME.length);
+    const slash = rest.indexOf("/");
+    if (slash <= 0) return null;
+    const name = rest.substring(0, slash);
+    const path = rest.substring(slash); // keeps the leading "/"
+    const base = overrides?.[name] ?? remotes?.[name];
+    if (base === undefined) return null;
+    // "" base = host-relative; trim a trailing slash otherwise
+    return (base.endsWith("/") ? base.substring(0, base.length - 1) : base) + path;
+}
+
+/** structural check for the version discriminator — the opener/sniffing entry point */
+export function isProjectDocument(value: unknown): value is ProjectDocument {
+    return !!value && typeof value === "object" && typeof (value as Record<string, unknown>)[PROJECT_DOCUMENT_KEY] === "string";
+}
+
+// ---------------------------------------------------------------------------
+// evaluation
+// ---------------------------------------------------------------------------
+
+export type ProjectEvaluationIssue = {
+    arc: "reference" | "def" | "over";
+    message: string;
+};
+
+/**
+ * Report evaluation issues to the console — in PRODUCTION too. Every issue
+ * means the document asked for something the runtime could not provide (a
+ * dropped def, an unresolved over, a failed asset), i.e. the loaded scene
+ * silently differs from what the author saved. The author debugs on the
+ * deployed page: gating this behind dev/?debugproject cost a full day of
+ * blind hunting when a deployed scene lost a component with a clean console
+ * (2026-09-01). A healthy document reports nothing.
+ */
+export function reportProjectIssues(issues: readonly ProjectEvaluationIssue[], warn: (message: string) => void = console.warn): void {
+    for (const issue of issues) {
+        warn(`[needle:project] ${issue.arc}: ${issue.message}`);
+    }
+}
+
+export type ProjectEvaluationResult = {
+    /** the object all non-mounted references were added to */
+    root: DocumentNode;
+    /** Placed reference roots by reference id. Populated during the host's scheduled
+     * composition phase, after template deserialization; await `completed` first. */
+    references: Map<string, DocumentNode>;
+    /** per-reference Model views by reference id (`scene` is that reference's placed
+     * INSTANCE; parser etc. come from the shared template). Populated at `completed`,
+     * like `references`. */
+    models: Map<string, DocumentModel>;
+    /**
+     * misses and errors — an issue never aborts evaluation, the arc is skipped.
+     * Populated up to `completed` (defs/overs apply in the host's composition phase).
+     */
+    issues: ProjectEvaluationIssue[];
+    /**
+     * Resolves once defs/overs have been applied. Hosts schedule composition after
+     * asset deserialization and before component activation. Needle's adapter uses
+     * its pre-setup phase, requiring a context tick; a vanilla host can run immediately.
+     */
+    completed: Promise<void>;
+};
+
+export type EvaluateProjectDocumentOptions = {
+    /** Reuse existing roots as named resolution scopes. Bindings may supply external
+     * host roots that have no asset reference in the document. When supplied, every
+     * declared scene reference must also be bound; a missing binding is reported
+     * instead of loading another instance. */
+    referenceBindings?: ReadonlyMap<string, DocumentNode>;
+    /** where references are placed; defaults to `context.scene` */
+    parent?: DocumentNode;
+    /** resolves `assets.src` for the document — tests/tools provide in-memory data here */
+    resolveAsset?: (assetId: string, src: string) => Promise<ArrayBuffer | string>;
+    /** base for resolving relative `assets.src` urls with the default (fetch) resolver */
+    baseUrl?: string;
+    /** per-environment overrides for the document's `remotes` table (known
+     * names only — the editor maps needle-cloud to its dev proxy); the
+     * document's own table is the default */
+    remotes?: Record<string, string>;
+    /**
+     * Rewrites a resource url (texture / external buffer) encountered while parsing an
+     * asset — the asset service's `resolveUrl` re-entering at load time. Needed for provider
+     * assets (e.g. PolyHaven) whose textures live at urls that plain relative resolution
+     * against `assets.src` cannot reach. Passed to the host's parse operation;
+     * the editor opener supplies it from `IAssetsService` so this
+     * evaluator carries NO provider knowledge.
+     */
+    resolveAssetUrl?: (assetId: string, url: string) => string;
+    /**
+     * AGGREGATE download progress across the document's assets: `loaded` bytes summed
+     * over all asset downloads, `total` summed over the known Content-Lengths (0 while
+     * nothing reported a length). Fired per received chunk — the loader chain adapts it
+     * to the ProgressEvent shape the loading UI expects.
+     */
+    onProgress?: (loaded: number, total: number) => void;
+};
+

package/src/document/validation.ts

@@ -0,0 +1,222 @@
+/**
+ * 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).
+ */
+
+/** a JSON Schema node — `true`/`false` schema forms are not used by our schema */
+type SchemaNode = Record<string, unknown>;
+
+export type SchemaValidationError = {
+    /** "/"-separated path to the offending value, relative to the document root */
+    readonly path: string;
+    readonly message: string;
+};
+
+/** 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: SchemaNode, value: unknown): SchemaValidationError[] {
+    const errors: SchemaValidationError[] = [];
+    validateNode(schema, value, "", schema, errors);
+    return errors;
+}
+
+/** one-line-per-error rendering for assertion messages */
+export function formatSchemaErrors(errors: readonly SchemaValidationError[]): string {
+    return errors.map(e => `  ${e.path || "<root>"}: ${e.message}`).join("\n");
+}
+
+function validateNode(schema: SchemaNode, value: unknown, path: string, root: SchemaNode, errors: SchemaValidationError[]): void {
+    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 as SchemaNode, 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: SchemaNode, path: string): void {
+    const bad = (keyword: string, expected: string): never => {
+        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: SchemaNode, value: unknown, root: SchemaNode): SchemaValidationError[] {
+    const errors: SchemaValidationError[] = [];
+    validateNode(schema, value, "", root, errors);
+    return errors;
+}
+
+function resolveRef(ref: string, root: SchemaNode): SchemaNode {
+    if (!ref.startsWith("#/")) throw new Error(`projectDocumentValidation: only local "#/..." $refs are supported, got "${ref}"`);
+    let current: unknown = 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: unknown, value: unknown): boolean {
+    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: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isSchema(value: unknown): value is SchemaNode {
+    return isPlainObject(value);
+}
+
+function join(path: string, segment: string): string {
+    return path ? `${path}/${segment}` : segment;
+}
+
+function describe(value: unknown): string {
+    if (value === null) return "null";
+    if (Array.isArray(value)) return "array";
+    if (value === undefined) return "undefined";
+    return typeof value;
+}
+
+function deepEquals(a: unknown, b: unknown): boolean {
+    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/src/document/write.ts

@@ -0,0 +1,112 @@
+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 function writePropertyOver(input: PropertyOverInput, encodeNode?: (object: object) => unknown): PropertyOverResult {
+    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: unknown): value is { ref: string; address?: NeedleAddress } {
+    if (!value || typeof value !== "object") return false;
+    const candidate = value as Record<string, unknown>;
+    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: unknown, encodeNode?: (object: object) => unknown): unknown {
+    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 as { isObject3D?: boolean }).isObject3D === true) {
+                return encodeNode?.(value);
+            }
+            const toArray = (value as { toArray?: unknown }).toArray;
+            if (typeof toArray === "function") {
+                const array = (value as { toArray(): unknown[] }).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: number[] = [];
+                    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: ProjectDocumentOver): string {
+    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: readonly ProjectDocumentOver[], newOvers: readonly ProjectDocumentOver[], liveRefs: ReadonlySet<string>, contentRefIds: ReadonlySet<string>, alwaysSuperseded?: ReadonlySet<string>, skipped?: string[]): ProjectDocumentOver[] {
+    const superseded = new Set(newOvers.map(documentOverKey));
+    const result: ProjectDocumentOver[] = [];
+    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/src/id.ts

@@ -16,6 +16,11 @@ export const NEEDLE_ID_KEY = "needle-id";
 
 // #region Derivation
 
+/** Stable instance identity, preserving the namespace used by Engine duplication. */
+export function deriveInstanceId(scope: string, originalId: string): string {
+    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/src/index.ts

@@ -1,6 +1,7 @@
 export { ANCHOR_MARKER, ANCHOR_MARKERS, parseAnchor, parseAnchorValue, type ParsedAnchor } from "./anchor.js";
 export {
     computeElementId,
+    deriveInstanceId,
     ensureIds,
     ensureNodeId,
     getElementId,
@@ -44,3 +45,5 @@ export {
 } 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";