@needle-tools/addressing 0.3.4 → 0.4.0

package/dist/document/index.d.ts

@@ -0,0 +1,8 @@
+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";

package/dist/document/index.js

@@ -0,0 +1,8 @@
+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";

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/runtime.d.ts

@@ -0,0 +1,71 @@
+import type { GraphNode } from "../address.js";
+import type { GltfAssociation } from "../loadedGltf.js";
+import type { ProjectEvaluationIssue } from "./types.js";
+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;
+}
+export interface DocumentModel {
+    scene?: DocumentNode;
+    scenes?: DocumentNode[];
+    animations?: object[];
+    parser?: {
+        json?: Record<string, unknown> & {
+            materials?: Array<{
+                name?: string;
+            }>;
+        };
+        associations?: Map<object, GltfAssociation>;
+        getDependency?(type: string, index: number): Promise<unknown>;
+    };
+}
+export type DocumentIssueReporter = (arc: ProjectEvaluationIssue["arc"], message: string) => void;
+export interface DocumentDefContext {
+    scene?: DocumentNode;
+    createNode(): DocumentNode;
+    applyComponent?(node: DocumentNode, data: {
+        name: string;
+    } & Record<string, unknown>, issue: (arc: "def", message: string) => void): void;
+}
+/** Loading and component lifecycle belong to the host; document rules do not. */
+export interface DocumentRuntime {
+    scene: DocumentNode;
+    renderer: object;
+    createNode(): DocumentNode;
+    createColor(value: number[]): object;
+    parse(data: ArrayBuffer | string, src: string, options?: {
+        resolveUrl(url: string): string;
+    }): Promise<DocumentModel | null>;
+    instantiate(template: DocumentNode, referenceId: string): DocumentNode | null;
+    parkTemplate(node: DocumentNode): void;
+    activateInstance(node: DocumentNode): void;
+    disposeTemplate(node: DocumentNode): void;
+    /** Run after template deserialization, before any instance activates its components. */
+    schedule(work: () => void): void;
+    loadEnvironment(url: string, options: {
+        format?: "pmrem";
+        name?: string;
+    }): Promise<object | null>;
+    createDefContext?(root: DocumentNode, baseUrl?: string): DocumentDefContext;
+    getComponents?(node: DocumentNode): object[];
+    matchesComponentType?(component: object, name: string): boolean;
+    matchesComponentGuid?(component: object, guid: string): boolean;
+    deriveComponentGuid?(referenceId: string, fileGuid: string): string;
+    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,225 @@
+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;
+    /**
+     * 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;
+};
+/**
+ * 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 = {
+    /** 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/dist/document/types.js

@@ -0,0 +1,43 @@
+/** the version discriminator key every project document must carry */
+export const PROJECT_DOCUMENT_KEY = "needle:project";
+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, remotes, overrides) {
+    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) {
+    return !!value && typeof value === "object" && typeof value[PROJECT_DOCUMENT_KEY] === "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, warn = console.warn) {
+    for (const issue of issues) {
+        warn(`[needle:project] ${issue.arc}: ${issue.message}`);
+    }
+}

package/dist/document/validation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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;
+};
+/**
+ * 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 declare function validateAgainstSchema(schema: SchemaNode, value: unknown): SchemaValidationError[];
+/** one-line-per-error rendering for assertion messages */
+export declare function formatSchemaErrors(errors: readonly SchemaValidationError[]): string;
+export {};