@needle-tools/addressing 0.3.4 → 0.4.0

package/src/document/index.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/src/document/inspection.ts

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

package/src/document/runtime.ts

@@ -0,0 +1,66 @@
+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/src/document/schema.json

@@ -0,0 +1,263 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://needle.tools/schemas/project-document-0.1.json",
+    "title": "Needle project document",
+    "description": "Composition-only document: it references glTF assets, places them (references), adds components (defs) and patches properties (overs). Content itself always lives in glTF — the document owns zero content. Spec: docs/project-format.md. Types: modules/needle-engine/js/package~/src/engine/project-document/engine_project_document.ts.",
+    "type": "object",
+    "required": ["needle:project"],
+    "properties": {
+        "needle:project": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Format version discriminator. Its presence IS the document sniff (isProjectDocument / parseSync). Current: \"0.1\"."
+        },
+        "metadata": {
+            "type": "object",
+            "description": "Layer metadata (USD layer-metadata analog). App-level, IGNORED by the runtime evaluator, preserved byte-faithfully on rewrite. Open set; known keys: name, description, image. RETIRED (2026-08-06): editorCamera and selection are per-user view state in the editor's local storage — readers may still find them in old documents (fallback-read), writers must not emit them."
+        },
+        "assets": {
+            "type": "object",
+            "description": "The loadable-resource POOL — the \"file\" half of every (file, id) address. An asset may exist here WITHOUT a reference (e.g. loaded only for a material an over binds).",
+            "additionalProperties": { "$ref": "#/definitions/asset" }
+        },
+        "remotes": {
+            "type": "object",
+            "description": "Named remote origins for `remote://<name>/<path>` srcs (the vscode filesystem model: the scheme routes, the AUTHORITY names the remote). Maps remote name → base url; consumers resolve srcs against it and MAY override known names per environment (the dev editor maps \"needle-cloud\" to its host-relative proxy). Repointing a project — dev↔prod, migrated storage — is one entry here, never a src rewrite.",
+            "additionalProperties": { "type": "string" }
+        },
+        "references": {
+            "type": "array",
+            "description": "USD reference arcs. Without an `address` a reference PLACES the asset's scene subtree; WITH an `address` it is an ENTITY reference instantiated into the composition's entity pool and never placed.",
+            "items": { "$ref": "#/definitions/reference" }
+        },
+        "bindings": {
+            "type": "array",
+            "description": "Host-owned roots required by this document. The host matches every binding before applying any edit and supplies the resulting objects to the evaluator.",
+            "items": { "$ref": "#/definitions/binding" }
+        },
+        "defs": {
+            "type": "array",
+            "description": "Add components to nodes, and (with `create`) DEFINE new nodes.",
+            "items": { "$ref": "#/definitions/def" }
+        },
+        "overs": {
+            "type": "array",
+            "description": "Property patches on existing content. Applied in document order — later entries win on the same target.",
+            "items": { "$ref": "#/definitions/over" }
+        },
+        "meta": {
+            "not": {},
+            "description": "RETIRED — renamed to `metadata` (clean break, no compat shim). Present only to fail loudly if a writer regresses."
+        }
+    },
+    "additionalProperties": true,
+
+    "definitions": {
+        "binding": {
+            "type": "object",
+            "required": ["id", "kind", "signature"],
+            "properties": {
+                "id": { "type": "string", "minLength": 1, "description": "Document-local reference used by targets. `$`-prefixed ids are reserved." },
+                "kind": { "const": "scene" },
+                "signature": { "type": "string", "minLength": 1, "description": "Stable structural identity used by the host to match this root before applying edits." },
+                "name": { "type": "string", "description": "Informational label for diagnostics only; never used as identity." },
+                "references": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+            },
+            "additionalProperties": true
+        },
+        "asset": {
+            "type": "object",
+            "required": ["src"],
+            "properties": {
+                "src": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Where the asset lives. Relative srcs resolve against the document (project folder); http(s) srcs stay absolute; `remote://<name>/<path>` srcs resolve via the document's `remotes` table (readers resolve BEFORE evaluation — the runtime never sees the scheme)."
+                },
+                "guid": {
+                    "type": "string",
+                    "description": "The file's STABLE identity (plans/file-identity-and-text-editing.md) — a client-minted uuid homed in the project's file registry (cloud: the revision manifest's guid column; local: .needle/files.json). Present for FOLDER FILES only; `src` is pure location, so a move/rename updates src while every reference keeps meaning this file. Served urls have no folder identity and omit it."
+                },
+                "asset": {
+                    "type": "object",
+                    "required": ["id"],
+                    "description": "Provider IDENTITY for assets whose resources (textures, buffers) live at provider-specific urls `src` alone cannot reach (e.g. PolyHaven). The HOST recovers the provider's resolver from this at load time; the engine evaluator ignores it. Self-contained assets omit it.",
+                    "properties": {
+                        "id": { "type": "string", "minLength": 1 },
+                        "provider": {
+                            "type": "string",
+                            "description": "Provider key hint — lets a cold session route straight to the owning provider instead of probing."
+                        }
+                    },
+                    "additionalProperties": true
+                },
+                "kind": {
+                    "type": "string",
+                    "enum": ["model", "material", "hdr", "texture", "image", "video", "audio", "code", "text", "document", "archive"],
+                    "description": "Semantic KIND, decided at USE time by the writer — 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 evaluator ignores it."
+                },
+                "etag": {
+                    "type": "string",
+                    "description": "INFORMATIONAL: the server ETag observed when the document captured the asset — lets a future reader detect that the upstream file changed since. Never used for loading decisions."
+                }
+            },
+            "additionalProperties": true
+        },
+
+        "reference": {
+            "type": "object",
+            "required": ["id", "asset"],
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Project-local id — the resolution SCOPE for every target naming it, and the entity handle for `{ ref }` values. Must be unique (duplicates are reported and skipped). Also the seed for the placed copy's stable guids. `$`-prefixed ids are RESERVED (see $scene)."
+                },
+                "asset": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Key into the document's `assets` map."
+                },
+                "address": {
+                    "$ref": "#/definitions/address",
+                    "description": "ENTITY-reference discriminator. When present, the addressed element INSIDE the asset is instantiated into the entity pool (never placed). An address of only a `type` means the asset ITSELF as that element kind (e.g. { type: \"hdr\" })."
+                },
+                "parent": {
+                    "not": {},
+                    "description": "RETIRED (2026-08-03, days after shipping) — structure is PURE OVERS: `{ target: { ref, path: \"parent\" }, value: { ref | \"$scene\", address?, index? } }`. One rail for mounts, reparenting and sibling order. Present only to fail loudly if a writer regresses."
+                },
+                "transform": {
+                    "not": {},
+                    "description": "RETIRED — placement is PURE OVERS (`{ ref, path: \"position\" }` etc.) so there is no precedence ambiguity between a transform field and a position over. Present only to fail loudly if a writer regresses."
+                }
+            },
+            "additionalProperties": true
+        },
+
+        "def": {
+            "type": "object",
+            "required": ["target"],
+            "anyOf": [
+                { "required": ["create"] },
+                { "required": ["components"] }
+            ],
+            "properties": {
+                "target": { "$ref": "#/definitions/target" },
+                "create": {
+                    "type": "object",
+                    "description": "The def DEFINES a node under the resolved target (composition root when the target is empty) and the components apply to IT. ADOPT semantics: when a child of that name already exists, the def COMPOSES onto it (transform applied, component data deserialized onto a matching existing component) — re-evaluation is idempotent, no twins.",
+                    "properties": {
+                        "id": { "type": "string", "minLength": 1, "description": "Stable needle-id assigned to the created node." },
+                        "name": { "type": "string" },
+                        "position": { "type": "array", "items": { "type": "number" }, "minItems": 3 },
+                        "quaternion": { "type": "array", "items": { "type": "number" }, "minItems": 4 },
+                        "scale": { "type": "array", "items": { "type": "number" }, "minItems": 3 },
+                        "copy": {
+                            "type": "object",
+                            "description": "Recreate a hierarchy duplicate from an addressed source. The seed reproduces the hierarchy identities. Entries sharing batch are cloned together in index order.",
+                            "required": ["source", "seed"],
+                            "anyOf": [
+                                { "required": ["batch", "index"] },
+                                {
+                                    "allOf": [
+                                        { "not": { "required": ["batch"] } },
+                                        { "not": { "required": ["index"] } }
+                                    ]
+                                }
+                            ],
+                            "properties": {
+                                "source": { "$ref": "#/definitions/target" },
+                                "seed": { "type": "string", "minLength": 1 },
+                                "reference": { "type": "boolean" },
+                                "batch": { "type": "string", "minLength": 1 },
+                                "index": { "type": "integer" }
+                            },
+                            "additionalProperties": true
+                        }
+                    },
+                    "additionalProperties": true
+                },
+                "components": {
+                    "type": "array",
+                    "description": "VERBATIM NEEDLE_components wire entries — no parallel vocabulary. Unknown component types are reported and skipped.",
+                    "items": {
+                        "type": "object",
+                        "required": ["name"],
+                        "properties": {
+                            "name": {
+                                "type": "string",
+                                "minLength": 1,
+                                "description": "TypeStore name. NOTE: runtime constructor names are decorator-wrapped (\"_DragControls\") — match by guid, not by ctor name."
+                            },
+                            "guid": { "type": "string" }
+                        },
+                        "additionalProperties": true
+                    }
+                }
+            },
+            "additionalProperties": true
+        },
+
+        "over": {
+            "type": "object",
+            "required": ["target", "value"],
+            "properties": {
+                "target": { "$ref": "#/definitions/overTarget" },
+                "value": {
+                    "description": "Primitive (including explicit null — on $scene slots like environment/background null means CLEAR; absence of the over means the boot default), array (three value types are patched in place via fromArray), or an entity-ref `{ ref }`. Other reference-valued forms ({ node }, { guid }, { asset, address }) are reported and SKIPPED, never raw-assigned."
+                }
+            },
+            "additionalProperties": true
+        },
+
+        "target": {
+            "type": "object",
+            "description": "Where an arc applies. `ref` selects the resolution scope; `address` locates an element inside it; `component` selects a component on the resolved node.",
+            "properties": {
+                "ref": {
+                    "type": "string",
+                    "description": "Reference id the address resolves WITHIN. Omitted → the composition root. Reserved: \"$scene\" = the context scene (scene-level opinions such as background/environment, or — with an address — a node inside the scene); \"$renderer\" = the context renderer (toneMapping, toneMappingExposure — no address allowed)."
+                },
+                "address": { "$ref": "#/definitions/address" },
+                "component": {
+                    "not": {},
+                    "description": "RETIRED — a component is reached through the PATH now (\"components/guid:<guid>/<field>\"), not a dedicated selector. Present only to fail loudly if a writer regresses."
+                },
+                "path": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "\"/\"-separated property path within the resolved element (e.g. \"material/map/repeat\"). 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. A bare numeric segment on an array is still an index. \"components\" is a synthesized segment on a node (the live userData layout stays private). Escaping follows RFC 6901 (\"~1\" = \"/\", \"~0\" = \"~\"). Reserved LAST segment: \"active\" (value false removes whatever the rest of the path resolved to — a node or a component — from the composed result; USD deactivation, referenced content is never deleted)."
+                }
+            },
+            "additionalProperties": true
+        },
+
+        "overTarget": {
+            "allOf": [
+                { "$ref": "#/definitions/target" },
+                {
+                    "type": "object",
+                    "required": ["path"],
+                    "description": "An over without a target path is reported and skipped by the evaluator."
+                }
+            ]
+        },
+
+        "address": {
+            "type": "object",
+            "description": "Fat address (@needle-tools/addressing). Resolution ladder: id → anchor → path. Recording several identifiers is the point — content changes underneath live edits.",
+            "properties": {
+                "type": {
+                    "type": "string",
+                    "description": "Element kind, e.g. \"node\" | \"material\" | \"mesh\" | \"hdr\". Materials resolve against the scope's meshes (id → name), not the graph."
+                },
+                "id": { "type": "string", "description": "needle-id — stamped in the asset, or DERIVED (deriving == stamping: the same (type, name, occurrence) rule on both sides, so capture-time derivation and load-time stamping always agree)." },
+                "name": { "type": "string" },
+                "anchor": { "type": "string" },
+                "path": { "type": "string", "description": "Node names from the asset root (exclusive) to the target (inclusive). Slash-separated segments use JSON-Pointer name escaping (~0 = ~, ~1 = /). An optional ~2n suffix selects the zero-based occurrence among same-named siblings; unqualified ambiguous segments do not resolve. Empty segments address unnamed children. An empty string is a valid one-segment path; absence means no path rung." },
+                "index": { "type": "integer", "description": "Weakest, reorder-fragile positional fallback." }
+            },
+            "additionalProperties": true
+        }
+    }
+}