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

package/dist/document/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./types.js";
+export * from "./runtime.js";
+export * from "./evaluate.js";
+export * from "./inspection.js";
+export * from "./validation.js";
+export * from "./write.js";
+export * from "./assets.js";
+export * from "./collectionSelector.js";
+export * from "./references.js";
+export * from './valueCodecs.js';
+export * from './loadedDocument.js';

package/dist/document/index.js

@@ -0,0 +1,11 @@
+export * from "./types.js";
+export * from "./runtime.js";
+export * from "./evaluate.js";
+export * from "./inspection.js";
+export * from "./validation.js";
+export * from "./write.js";
+export * from "./assets.js";
+export * from "./collectionSelector.js";
+export * from "./references.js";
+export * from './valueCodecs.js';
+export * from './loadedDocument.js';

package/dist/document/inspection.d.ts

@@ -0,0 +1,30 @@
+import { type GraphNode, type NeedleAddress } from "../index.js";
+export type ProjectInspectionTarget = {
+    ref: string;
+    address?: NeedleAddress;
+    pathPrefix?: string;
+};
+type Node = GraphNode & {
+    parent?: Node | null;
+    isObject3D?: boolean;
+};
+/** Reference membership is captured at placement, before parent overs move nodes. */
+export declare class ProjectDocumentInspection {
+    private readonly scene;
+    private readonly scopes;
+    private readonly targets;
+    ready: Promise<void>;
+    constructor(scene: Node);
+    registerReference(ref: string, root: object, elements?: Iterable<object>, referenceRoots?: ReadonlySet<object>): void;
+    resolve(target: ProjectInspectionTarget): object | null;
+    targetFor(object: object): ProjectInspectionTarget | null;
+    private inScene;
+}
+/** Opt in before loading a document; ordinary playback allocates no inspection index. */
+export declare function enableProjectDocumentInspection(): {
+    dispose(): void;
+};
+export declare function createProjectDocumentInspection(scene: Node): ProjectDocumentInspection | undefined;
+export declare function getProjectDocumentInspection(context: object): ProjectDocumentInspection | undefined;
+export declare function registerProjectDocumentInspection(context: object, inspection: ProjectDocumentInspection): void;
+export {};

package/dist/document/inspection.js

@@ -0,0 +1,130 @@
+import { resolveDocumentCollectionElement } from "./collectionSelector.js";
+import { joinPath, parseAnchorValue, resolveInCollection, resolveInGraph, splitPath } from "../index.js";
+/** Reference membership is captured at placement, before parent overs move nodes. */
+export class ProjectDocumentInspection {
+    constructor(scene) {
+        this.scene = scene;
+        this.scopes = new Map();
+        this.targets = new WeakMap();
+        this.ready = Promise.resolve();
+    }
+    registerReference(ref, root, elements = [], referenceRoots) {
+        const nodes = new Map();
+        const scope = { root: new WeakRef(root), nodes, elements: [] };
+        const capture = (node, path) => {
+            const weak = new WeakRef(node);
+            const graph = {
+                get name() { return weak.deref()?.name; },
+                get userData() { return weak.deref()?.userData; },
+                children: node.children?.filter(child => !referenceRoots?.has(child))
+                    .map(child => capture(child, [...path, child.name ?? ""])),
+            };
+            nodes.set(graph, weak);
+            const id = node.userData?.["needle-id"];
+            const anchor = parseAnchorValue(node.name);
+            const address = node === root ? undefined : {
+                type: "node", path: joinPath(path), ...(typeof id === "string" ? { id } : {}), ...(anchor ? { anchor } : {}),
+            };
+            if (node === root || address)
+                this.targets.set(node, { ref, ...(address ? { address } : {}) });
+            return graph;
+        };
+        if (root.isObject3D)
+            scope.graph = capture(root, []);
+        else
+            this.targets.set(root, { ref });
+        for (const element of elements) {
+            const value = element;
+            const type = value.isMaterial ? "material" : value.isTexture ? "texture" : value.isAnimationClip ? "animation" : null;
+            if (!type)
+                continue;
+            scope.elements.push(new WeakRef(element));
+            const id = value.userData?.["needle-id"];
+            if (typeof id === "string")
+                this.targets.set(element, { ref, address: { type, id, name: value.name } });
+        }
+        this.scopes.set(ref, scope);
+    }
+    resolve(target) {
+        const scope = this.scopes.get(target.ref);
+        let object = target.ref === "$scene" ? this.scene : scope?.root.deref() ?? null;
+        if (target.address) {
+            const address = target.address;
+            if (address.type && address.type !== "node") {
+                const elements = scope?.elements.flatMap(weak => {
+                    const value = weak.deref();
+                    const matches = address.type === "material" ? value?.isMaterial : address.type === "texture" ? value?.isTexture : address.type === "animation" ? value?.isAnimationClip : false;
+                    return value && matches ? [value] : [];
+                }) ?? [];
+                object = resolveInCollection(address, elements);
+            }
+            else if (scope?.graph) {
+                const graph = resolveInGraph(address, scope.graph);
+                object = graph ? scope.nodes.get(graph)?.deref() ?? null : null;
+                if (object && !this.inScene(object))
+                    object = null;
+            }
+            else
+                object = target.ref === "$scene" ? resolveInGraph(address, this.scene) : null;
+        }
+        if (!object)
+            return null;
+        if (object.isObject3D && !this.inScene(object))
+            return null;
+        if (target.pathPrefix) {
+            const parts = splitPath(target.pathPrefix.replace(/\/$/, ""));
+            for (const part of parts) {
+                if (part === "components")
+                    object = object.userData?.components ?? null;
+                else if (Array.isArray(object) && part.startsWith("guid:")) {
+                    const guid = part.slice(5);
+                    object = resolveDocumentCollectionElement(object, `guid:${guid}`) ?? null;
+                }
+                else
+                    return null;
+                if (!object)
+                    return null;
+            }
+        }
+        return object;
+    }
+    targetFor(object) {
+        if (object === this.scene)
+            return { ref: "$scene" };
+        const component = object;
+        const guid = component.needle_editor_guid || component.guid;
+        if (component.gameObject && guid) {
+            const host = this.targetFor(component.gameObject);
+            return host ? { ...host, pathPrefix: `components/guid:${guid}/` } : null;
+        }
+        const target = this.targets.get(object);
+        return target && this.resolve(target) === object ? structuredClone(target) : null;
+    }
+    inScene(object) {
+        // Liveness only; reference ownership comes from the placement scope above.
+        for (let node = object; node; node = node.parent)
+            if (node === this.scene)
+                return true;
+        return false;
+    }
+}
+const inspections = new WeakMap();
+let observers = 0;
+/** Opt in before loading a document; ordinary playback allocates no inspection index. */
+export function enableProjectDocumentInspection() {
+    observers++;
+    let disposed = false;
+    return { dispose() { if (!disposed) {
+            disposed = true;
+            observers--;
+        } } };
+}
+export function createProjectDocumentInspection(scene) {
+    return observers ? new ProjectDocumentInspection(scene) : undefined;
+}
+export function getProjectDocumentInspection(context) {
+    return inspections.get(context);
+}
+export function registerProjectDocumentInspection(context, inspection) {
+    inspections.set(context, inspection);
+}

package/dist/document/loadedDocument.d.ts

@@ -0,0 +1,18 @@
+import { type ProjectInspectionTarget } from './inspection.js';
+import type { DocumentModel, DocumentNode, DocumentRuntime } from './runtime.js';
+import type { EvaluateProjectDocumentOptions, ProjectDocument, ProjectEvaluationIssue } from './types.js';
+export type ReadonlyDocument<T> = T extends object ? {
+    readonly [K in keyof T]: ReadonlyDocument<T[K]>;
+} : T;
+/** Evaluated document data and live address resolution, independent of the host runtime. */
+export interface LoadedProjectDocument {
+    readonly document: ReadonlyDocument<ProjectDocument>;
+    readonly root: DocumentNode;
+    readonly references: ReadonlyMap<string, DocumentNode>;
+    readonly models: ReadonlyMap<string, DocumentModel>;
+    readonly issues: readonly ProjectEvaluationIssue[];
+    resolve(target: ProjectInspectionTarget): object | null;
+    addressOf(object: object): ProjectInspectionTarget | null;
+}
+/** The caller owns fetching, cancellation, rendering and disposal of runtime resources. */
+export declare function loadProjectDocument(runtime: DocumentRuntime, document: ProjectDocument, options?: EvaluateProjectDocumentOptions): Promise<LoadedProjectDocument>;

package/dist/document/loadedDocument.js

@@ -0,0 +1,35 @@
+import { evaluateProjectDocument } from './evaluate.js';
+import { enableProjectDocumentInspection, getProjectDocumentInspection } from './inspection.js';
+/** The caller owns fetching, cancellation, rendering and disposal of runtime resources. */
+export async function loadProjectDocument(runtime, document, options) {
+    const snapshot = structuredClone(document);
+    const observation = enableProjectDocumentInspection();
+    try {
+        const result = await evaluateProjectDocument(runtime, snapshot, options);
+        await result.completed;
+        const index = getProjectDocumentInspection(runtime.inspectionOwner ?? runtime);
+        if (!index)
+            throw new Error('Document address index is unavailable');
+        await index.ready;
+        freezeDocument(snapshot);
+        return {
+            document: snapshot,
+            root: result.root,
+            references: new Map(result.references),
+            models: new Map(result.models),
+            issues: [...result.issues],
+            resolve: target => index.resolve(target),
+            addressOf: object => index.targetFor(object),
+        };
+    }
+    finally {
+        observation.dispose();
+    }
+}
+function freezeDocument(value) {
+    if (!value || typeof value !== 'object' || Object.isFrozen(value))
+        return;
+    for (const child of Object.values(value))
+        freezeDocument(child);
+    Object.freeze(value);
+}

package/dist/document/references.d.ts

@@ -0,0 +1,7 @@
+import type { ProjectDocumentTarget } from './types.js';
+/** Undefined means ordinary data; null means a recognized reference whose target is missing. */
+export type DocumentNodeReferenceResolver = (target: ProjectDocumentTarget & {
+    ref: string;
+}) => object | null | undefined;
+/** Copy-on-write resolution shared by document loading and component snapshot restoration. */
+export declare function resolveDocumentNodeReferences(value: unknown, resolve: DocumentNodeReferenceResolver, issue: (arc: 'def', message: string) => void): unknown;

package/dist/document/references.js

@@ -0,0 +1,36 @@
+/** Copy-on-write resolution shared by document loading and component snapshot restoration. */
+export function resolveDocumentNodeReferences(value, resolve, issue) {
+    if (!value || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value)) {
+        let copy = null;
+        for (let i = 0; i < value.length; i++) {
+            const resolved = resolveDocumentNodeReferences(value[i], resolve, issue);
+            if (resolved !== value[i]) {
+                if (!copy)
+                    copy = [...value];
+                copy[i] = resolved;
+            }
+        }
+        return copy ?? value;
+    }
+    if (typeof value.ref === 'string') {
+        const resolved = resolve(value);
+        if (resolved === null) {
+            issue('def', `node reference did not resolve: ${JSON.stringify(value)}`);
+            return undefined;
+        }
+        if (resolved !== undefined)
+            return resolved;
+    }
+    let copy = null;
+    for (const [key, entry] of Object.entries(value)) {
+        const resolved = resolveDocumentNodeReferences(entry, resolve, issue);
+        if (resolved !== entry) {
+            if (!copy)
+                copy = { ...value };
+            copy[key] = resolved;
+        }
+    }
+    return copy ?? value;
+}

package/dist/document/runtime.d.ts

@@ -0,0 +1,119 @@
+import type { GraphNode } from "../address.js";
+import type { GltfAssociation } from "../loadedGltf.js";
+import type { ProjectEvaluationIssue } from "./types.js";
+/** Converts runtime vectors and rotations to and from document arrays. */
+export interface DocumentVector {
+    fromArray(value: number[]): unknown;
+    toArray(): number[];
+}
+/** The scene operations used by composition, independent of a three.js build. */
+export interface DocumentNode extends GraphNode {
+    name: string;
+    isObject3D: boolean;
+    userData: Record<string, unknown>;
+    parent: DocumentNode | null;
+    children: DocumentNode[];
+    position: DocumentVector;
+    quaternion: DocumentVector;
+    scale: DocumentVector;
+    add(...nodes: DocumentNode[]): unknown;
+    removeFromParent(): unknown;
+    traverse(visitor: (node: DocumentNode) => void): void;
+}
+/** Loaded asset scenes and metadata used to resolve document targets. */
+export interface DocumentModel {
+    /** Default scene used as the template for document references. */
+    scene?: DocumentNode;
+    /** Loaded scenes used when attaching stable node IDs from glTF metadata. */
+    scenes?: DocumentNode[];
+    /** Loaded clips available for address resolution; loading does not play them. */
+    animations?: object[];
+    /** Optional glTF loader metadata used to resolve asset objects and materials. */
+    parser?: {
+        /** Source glTF data used for stable node IDs and material lookup. */
+        json?: Record<string, unknown> & {
+            materials?: Array<{
+                name?: string;
+            }>;
+        };
+        /** Maps loaded objects to their source glTF indices. */
+        associations?: Map<object, GltfAssociation>;
+        /** Loads a source resource by kind and index; used here for materials. */
+        getDependency?(type: string, index: number): Promise<unknown>;
+    };
+}
+/** Reports which document operation could not be applied and why. */
+export type DocumentIssueReporter = (arc: ProjectEvaluationIssue["arc"], message: string) => void;
+/** Scene and component hooks used while applying document definitions. */
+export interface DocumentDefContext {
+    /** Runtime scene available to definition readers. */
+    scene?: DocumentNode;
+    /** Creates an unattached node for a definition's `create` entry. */
+    createNode(): DocumentNode;
+    /** Legacy reader for component definitions without an extension owner. */
+    applyComponent?(node: DocumentNode, data: {
+        name: string;
+    } & Record<string, unknown>, issue: (arc: "def", message: string) => void): void;
+    /** Readers for owned definitions, keyed by document extension ID. */
+    readonly extensions?: ReadonlyMap<string, DocumentExtensionProvider>;
+}
+/** Reads one extension's saved data using the declared version and migrations. */
+export interface DocumentExtensionProvider {
+    /** Current saved-data version understood by this reader. */
+    readonly version: number;
+    /** Typed property values supported by this extension version. */
+    readonly valueCodecs?: Readonly<Record<string, import('./valueCodecs.js').DocumentValueCodec>>;
+    /** Source version to migration function; each function produces the current format. */
+    readonly migrations?: Readonly<Record<number, (data: Record<string, unknown>) => Record<string, unknown>>>;
+    /** Omit when this extension cannot restore component data. */
+    readonly components?: {
+        /** Applies one component's resolved data to its target node. */
+        apply(node: DocumentNode, data: {
+            name: string;
+        } & Record<string, unknown>, issue: (arc: "def", message: string) => void): void;
+    };
+}
+/** Host operations used by the shared evaluator to load assets and apply document data. */
+export interface DocumentRuntime {
+    /** Default parent for composed document content. */
+    scene: DocumentNode;
+    /** Host renderer targeted by renderer property overrides. */
+    renderer: object;
+    /** Creates an unattached scene node. */
+    createNode(): DocumentNode;
+    /** Converts document color channels into the host's color value. */
+    createColor(value: number[]): object;
+    /** Parses asset data, using `src` as its identity and relative-resource base. */
+    parse(data: ArrayBuffer | string, src: string, options?: {
+        resolveUrl(url: string): string;
+    }): Promise<DocumentModel | null>;
+    /** Creates a reference instance from a loaded template. */
+    clone(template: DocumentNode, referenceId: string): DocumentNode | null;
+    /** Keeps a loaded template inactive while reference instances are composed. */
+    parkTemplate(node: DocumentNode): void;
+    /** Enables a placed reference instance through the host's lifecycle. */
+    activateInstance(node: DocumentNode): void;
+    /** Releases a template after cloning without destroying its placed instances. */
+    disposeTemplate(node: DocumentNode): void;
+    /** Run after template deserialization, before any instance activates its components. */
+    schedule(work: () => void): void;
+    /** Loads the host's environment resource for a document environment URL. */
+    loadEnvironment(url: string, options: {
+        format?: "pmrem";
+        name?: string;
+    }): Promise<object | null>;
+    /** Binds definition readers to the composed root and document URL. */
+    createDefContext?(root: DocumentNode, baseUrl?: string): DocumentDefContext;
+    /** Lists components attached to a node for component-target resolution. */
+    getComponents?(node: DocumentNode): object[];
+    /** Matches a component against its saved type name. */
+    matchesComponentType?(component: object, name: string): boolean;
+    /** Matches a component against its saved stable ID. */
+    matchesComponentGuid?(component: object, guid: string): boolean;
+    /** Derives an instance component ID from its reference and source-file IDs. */
+    deriveComponentGuid?(referenceId: string, fileGuid: string): string;
+    /** Removes a component through the host's lifecycle; owner may be unresolved. */
+    removeComponent?(component: object, owner: DocumentNode | null): void;
+    /** Identity used by the optional inspection registry; defaults to the runtime itself. */
+    inspectionOwner?: object;
+}

package/dist/document/runtime.js

@@ -0,0 +1 @@
+export {};

package/dist/document/types.d.ts

@@ -0,0 +1,240 @@
+import type { NeedleAddress } from "../address.js";
+import type { DocumentNode, DocumentModel } from "./runtime.js";
+/** the version discriminator key every project document must carry */
+export declare 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;
+    /** Owner of all component entries in this def; omitted for legacy data. */
+    extension?: string;
+    /**
+     * 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;
+};
+/** Saved-data version required from an extension, independent of its package version. */
+export type ProjectDocumentExtension = {
+    version: number;
+};
+export type ProjectDocument = {
+    [PROJECT_DOCUMENT_KEY]: string;
+    /** layer metadata (USD's "layer metadata" concept — e.g. `name`); free-form */
+    metadata?: Record<string, unknown>;
+    /** Required document extensions, not installed packages or runtime dependencies. */
+    extensions?: Record<string, ProjectDocumentExtension>;
+    /** 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;
+};
+/**
+ * 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 declare function resolveDocumentRemoteSrc(src: string, remotes: Record<string, string> | undefined, overrides?: Record<string, string>): string | null;
+/** structural check for the version discriminator — the opener/sniffing entry point */
+export declare function isProjectDocument(value: unknown): value is ProjectDocument;
+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 declare function reportProjectIssues(issues: readonly ProjectEvaluationIssue[], warn?: (message: string) => void): void;
+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 = {
+    /** Restore components on existing nodes without loading assets or replaying structural edits. */
+    componentRecovery?: {
+        readonly signal: AbortSignal;
+        readonly resolveTarget: (target: ProjectDocumentTarget) => DocumentNode | null;
+    };
+    /** Resolve extension readers after loading, in the runtime's pre-activation context. */
+    extensions?: (context: import('./runtime.js').DocumentDefContext) => ReadonlyMap<string, import('./runtime.js').DocumentExtensionProvider>;
+    /** 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;
+};