@needle-tools/addressing 0.3.4 → 0.4.0-1791982227.dramatic-tempura.8b3a85e
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/Readme.md +151 -70
- package/dist/address.d.ts +5 -0
- package/dist/address.js +25 -3
- package/dist/document/assets.d.ts +27 -0
- package/dist/document/assets.js +75 -0
- package/dist/document/collectionSelector.d.ts +9 -0
- package/dist/document/collectionSelector.js +29 -0
- package/dist/document/evaluate.d.ts +86 -0
- package/dist/document/evaluate.js +1082 -0
- package/dist/document/index.d.ts +11 -0
- package/dist/document/index.js +11 -0
- package/dist/document/inspection.d.ts +30 -0
- package/dist/document/inspection.js +130 -0
- package/dist/document/loadedDocument.d.ts +18 -0
- package/dist/document/loadedDocument.js +35 -0
- package/dist/document/references.d.ts +7 -0
- package/dist/document/references.js +36 -0
- package/dist/document/runtime.d.ts +119 -0
- package/dist/document/runtime.js +1 -0
- package/dist/document/types.d.ts +240 -0
- package/dist/document/types.js +43 -0
- package/dist/document/validation.d.ts +36 -0
- package/dist/document/validation.js +222 -0
- package/dist/document/valueCodecs.d.ts +20 -0
- package/dist/document/valueCodecs.js +3 -0
- package/dist/document/write.d.ts +31 -0
- package/dist/document/write.js +131 -0
- package/dist/id.d.ts +2 -0
- package/dist/id.js +4 -0
- package/dist/index.d.ts +2 -1
- package/dist/index.js +2 -1
- package/dist/loadedGltf.d.ts +32 -0
- package/dist/loadedGltf.js +62 -0
- package/dist/resolve.js +8 -6
- package/package.json +10 -2
- package/src/address.ts +169 -144
- package/src/anchor.ts +71 -71
- package/src/document/assets.ts +77 -0
- package/src/document/collectionSelector.ts +37 -0
- package/src/document/evaluate.ts +1111 -0
- package/src/document/index.ts +11 -0
- package/src/document/inspection.ts +123 -0
- package/src/document/loadedDocument.ts +48 -0
- package/src/document/references.ts +41 -0
- package/src/document/runtime.ts +113 -0
- package/src/document/schema.json +293 -0
- package/src/document/types.ts +265 -0
- package/src/document/validation.ts +226 -0
- package/src/document/valueCodecs.ts +23 -0
- package/src/document/write.ts +132 -0
- package/src/gltf.ts +33 -33
- package/src/hash.ts +58 -58
- package/src/id.ts +206 -201
- package/src/index.ts +49 -46
- package/src/loadedGltf.ts +93 -0
- package/src/resolve.ts +319 -317
- package/src/target.ts +126 -126
- package/src/uuid.ts +48 -48
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
export * from "./types.js";
|
|
2
|
+
export * from "./runtime.js";
|
|
3
|
+
export * from "./evaluate.js";
|
|
4
|
+
export * from "./inspection.js";
|
|
5
|
+
export * from "./validation.js";
|
|
6
|
+
export * from "./write.js";
|
|
7
|
+
export * from "./assets.js";
|
|
8
|
+
export * from "./collectionSelector.js";
|
|
9
|
+
export * from "./references.js";
|
|
10
|
+
export * from './valueCodecs.js';
|
|
11
|
+
export * from './loadedDocument.js';
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
import { resolveDocumentCollectionElement } from "./collectionSelector.js";
|
|
2
|
+
import { joinPath, parseAnchorValue, resolveInCollection, resolveInGraph, splitPath, type GraphNode, type NeedleAddress } from "../index.js";
|
|
3
|
+
|
|
4
|
+
export type ProjectInspectionTarget = { ref: string; address?: NeedleAddress; pathPrefix?: string };
|
|
5
|
+
type Node = GraphNode & { parent?: Node | null; isObject3D?: boolean };
|
|
6
|
+
type Element = { name?: string; userData?: Record<string, unknown>; isMaterial?: boolean; isTexture?: boolean; isAnimationClip?: boolean };
|
|
7
|
+
type Scope = { root: WeakRef<object>; graph?: GraphNode; nodes: Map<GraphNode, WeakRef<object>>; elements: WeakRef<object>[] };
|
|
8
|
+
|
|
9
|
+
/** Reference membership is captured at placement, before parent overs move nodes. */
|
|
10
|
+
export class ProjectDocumentInspection {
|
|
11
|
+
private readonly scopes = new Map<string, Scope>();
|
|
12
|
+
private readonly targets = new WeakMap<object, ProjectInspectionTarget>();
|
|
13
|
+
ready: Promise<void> = Promise.resolve();
|
|
14
|
+
|
|
15
|
+
constructor(private readonly scene: Node) {}
|
|
16
|
+
|
|
17
|
+
registerReference(ref: string, root: object, elements: Iterable<object> = [], referenceRoots?: ReadonlySet<object>): void {
|
|
18
|
+
const nodes = new Map<GraphNode, WeakRef<object>>();
|
|
19
|
+
const scope: Scope = { root: new WeakRef(root), nodes, elements: [] };
|
|
20
|
+
const capture = (node: Node, path: string[]): GraphNode => {
|
|
21
|
+
const weak = new WeakRef(node);
|
|
22
|
+
const graph: GraphNode = {
|
|
23
|
+
get name() { return weak.deref()?.name; },
|
|
24
|
+
get userData() { return weak.deref()?.userData; },
|
|
25
|
+
children: node.children?.filter(child => !referenceRoots?.has(child))
|
|
26
|
+
.map(child => capture(child as Node, [...path, child.name ?? ""])),
|
|
27
|
+
};
|
|
28
|
+
nodes.set(graph, weak);
|
|
29
|
+
const id = node.userData?.["needle-id"];
|
|
30
|
+
const anchor = parseAnchorValue(node.name);
|
|
31
|
+
const address: NeedleAddress | undefined = node === root ? undefined : {
|
|
32
|
+
type: "node", path: joinPath(path), ...(typeof id === "string" ? { id } : {}), ...(anchor ? { anchor } : {}),
|
|
33
|
+
};
|
|
34
|
+
if (node === root || address) this.targets.set(node, { ref, ...(address ? { address } : {}) });
|
|
35
|
+
return graph;
|
|
36
|
+
};
|
|
37
|
+
if ((root as Node).isObject3D) scope.graph = capture(root as Node, []);
|
|
38
|
+
else this.targets.set(root, { ref });
|
|
39
|
+
for (const element of elements) {
|
|
40
|
+
const value = element as Element;
|
|
41
|
+
const type = value.isMaterial ? "material" : value.isTexture ? "texture" : value.isAnimationClip ? "animation" : null;
|
|
42
|
+
if (!type) continue;
|
|
43
|
+
scope.elements.push(new WeakRef(element));
|
|
44
|
+
const id = value.userData?.["needle-id"];
|
|
45
|
+
if (typeof id === "string") this.targets.set(element, { ref, address: { type, id, name: value.name } });
|
|
46
|
+
}
|
|
47
|
+
this.scopes.set(ref, scope);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
resolve(target: ProjectInspectionTarget): object | null {
|
|
51
|
+
const scope = this.scopes.get(target.ref);
|
|
52
|
+
let object: object | null = target.ref === "$scene" ? this.scene : scope?.root.deref() ?? null;
|
|
53
|
+
if (target.address) {
|
|
54
|
+
const address = target.address;
|
|
55
|
+
if (address.type && address.type !== "node") {
|
|
56
|
+
const elements = scope?.elements.flatMap(weak => {
|
|
57
|
+
const value = weak.deref() as Element | undefined;
|
|
58
|
+
const matches = address.type === "material" ? value?.isMaterial : address.type === "texture" ? value?.isTexture : address.type === "animation" ? value?.isAnimationClip : false;
|
|
59
|
+
return value && matches ? [value] : [];
|
|
60
|
+
}) ?? [];
|
|
61
|
+
object = resolveInCollection(address, elements);
|
|
62
|
+
} else if (scope?.graph) {
|
|
63
|
+
const graph = resolveInGraph(address, scope.graph);
|
|
64
|
+
object = graph ? scope.nodes.get(graph)?.deref() ?? null : null;
|
|
65
|
+
if (object && !this.inScene(object as Node)) object = null;
|
|
66
|
+
} else object = target.ref === "$scene" ? resolveInGraph(address, this.scene) : null;
|
|
67
|
+
}
|
|
68
|
+
if (!object) return null;
|
|
69
|
+
if ((object as Node).isObject3D && !this.inScene(object as Node)) return null;
|
|
70
|
+
if (target.pathPrefix) {
|
|
71
|
+
const parts = splitPath(target.pathPrefix.replace(/\/$/, ""));
|
|
72
|
+
for (const part of parts) {
|
|
73
|
+
if (part === "components") object = (object as Node).userData?.components as object ?? null;
|
|
74
|
+
else if (Array.isArray(object) && part.startsWith("guid:")) {
|
|
75
|
+
const guid = part.slice(5);
|
|
76
|
+
object = resolveDocumentCollectionElement(object, `guid:${guid}`) as object ?? null;
|
|
77
|
+
} else return null;
|
|
78
|
+
if (!object) return null;
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
return object;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
targetFor(object: object): ProjectInspectionTarget | null {
|
|
85
|
+
if (object === this.scene) return { ref: "$scene" };
|
|
86
|
+
const component = object as { gameObject?: object; needle_editor_guid?: string; guid?: string };
|
|
87
|
+
const guid = component.needle_editor_guid || component.guid;
|
|
88
|
+
if (component.gameObject && guid) {
|
|
89
|
+
const host = this.targetFor(component.gameObject);
|
|
90
|
+
return host ? { ...host, pathPrefix: `components/guid:${guid}/` } : null;
|
|
91
|
+
}
|
|
92
|
+
const target = this.targets.get(object);
|
|
93
|
+
return target && this.resolve(target) === object ? structuredClone(target) : null;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
private inScene(object: Node): boolean {
|
|
97
|
+
// Liveness only; reference ownership comes from the placement scope above.
|
|
98
|
+
for (let node: Node | null | undefined = object; node; node = node.parent) if (node === this.scene) return true;
|
|
99
|
+
return false;
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
const inspections = new WeakMap<object, ProjectDocumentInspection>();
|
|
104
|
+
let observers = 0;
|
|
105
|
+
|
|
106
|
+
/** Opt in before loading a document; ordinary playback allocates no inspection index. */
|
|
107
|
+
export function enableProjectDocumentInspection(): { dispose(): void } {
|
|
108
|
+
observers++;
|
|
109
|
+
let disposed = false;
|
|
110
|
+
return { dispose() { if (!disposed) { disposed = true; observers--; } } };
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
export function createProjectDocumentInspection(scene: Node): ProjectDocumentInspection | undefined {
|
|
114
|
+
return observers ? new ProjectDocumentInspection(scene) : undefined;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
export function getProjectDocumentInspection(context: object): ProjectDocumentInspection | undefined {
|
|
118
|
+
return inspections.get(context);
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
export function registerProjectDocumentInspection(context: object, inspection: ProjectDocumentInspection): void {
|
|
122
|
+
inspections.set(context, inspection);
|
|
123
|
+
}
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import { evaluateProjectDocument } from './evaluate.js';
|
|
2
|
+
import { enableProjectDocumentInspection, getProjectDocumentInspection, type ProjectInspectionTarget } from './inspection.js';
|
|
3
|
+
import type { DocumentModel, DocumentNode, DocumentRuntime } from './runtime.js';
|
|
4
|
+
import type { EvaluateProjectDocumentOptions, ProjectDocument, ProjectEvaluationIssue } from './types.js';
|
|
5
|
+
|
|
6
|
+
export type ReadonlyDocument<T> = T extends object ? { readonly [K in keyof T]: ReadonlyDocument<T[K]> } : T;
|
|
7
|
+
|
|
8
|
+
/** Evaluated document data and live address resolution, independent of the host runtime. */
|
|
9
|
+
export interface LoadedProjectDocument {
|
|
10
|
+
readonly document: ReadonlyDocument<ProjectDocument>;
|
|
11
|
+
readonly root: DocumentNode;
|
|
12
|
+
readonly references: ReadonlyMap<string, DocumentNode>;
|
|
13
|
+
readonly models: ReadonlyMap<string, DocumentModel>;
|
|
14
|
+
readonly issues: readonly ProjectEvaluationIssue[];
|
|
15
|
+
resolve(target: ProjectInspectionTarget): object | null;
|
|
16
|
+
addressOf(object: object): ProjectInspectionTarget | null;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/** The caller owns fetching, cancellation, rendering and disposal of runtime resources. */
|
|
20
|
+
export async function loadProjectDocument(runtime: DocumentRuntime, document: ProjectDocument, options?: EvaluateProjectDocumentOptions): Promise<LoadedProjectDocument> {
|
|
21
|
+
const snapshot = structuredClone(document);
|
|
22
|
+
const observation = enableProjectDocumentInspection();
|
|
23
|
+
try {
|
|
24
|
+
const result = await evaluateProjectDocument(runtime, snapshot, options);
|
|
25
|
+
await result.completed;
|
|
26
|
+
const index = getProjectDocumentInspection(runtime.inspectionOwner ?? runtime);
|
|
27
|
+
if (!index) throw new Error('Document address index is unavailable');
|
|
28
|
+
await index.ready;
|
|
29
|
+
freezeDocument(snapshot);
|
|
30
|
+
return {
|
|
31
|
+
document: snapshot,
|
|
32
|
+
root: result.root,
|
|
33
|
+
references: new Map(result.references),
|
|
34
|
+
models: new Map(result.models),
|
|
35
|
+
issues: [...result.issues],
|
|
36
|
+
resolve: target => index.resolve(target),
|
|
37
|
+
addressOf: object => index.targetFor(object),
|
|
38
|
+
};
|
|
39
|
+
} finally {
|
|
40
|
+
observation.dispose();
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
function freezeDocument(value: unknown): void {
|
|
45
|
+
if (!value || typeof value !== 'object' || Object.isFrozen(value)) return;
|
|
46
|
+
for (const child of Object.values(value)) freezeDocument(child);
|
|
47
|
+
Object.freeze(value);
|
|
48
|
+
}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import type { ProjectDocumentTarget } from './types.js';
|
|
2
|
+
|
|
3
|
+
/** Undefined means ordinary data; null means a recognized reference whose target is missing. */
|
|
4
|
+
export type DocumentNodeReferenceResolver = (target: ProjectDocumentTarget & { ref: string }) => object | null | undefined;
|
|
5
|
+
|
|
6
|
+
/** Copy-on-write resolution shared by document loading and component snapshot restoration. */
|
|
7
|
+
export function resolveDocumentNodeReferences(
|
|
8
|
+
value: unknown,
|
|
9
|
+
resolve: DocumentNodeReferenceResolver,
|
|
10
|
+
issue: (arc: 'def', message: string) => void,
|
|
11
|
+
): unknown {
|
|
12
|
+
if (!value || typeof value !== 'object') return value;
|
|
13
|
+
if (Array.isArray(value)) {
|
|
14
|
+
let copy: unknown[] | null = null;
|
|
15
|
+
for (let i = 0; i < value.length; i++) {
|
|
16
|
+
const resolved = resolveDocumentNodeReferences(value[i], resolve, issue);
|
|
17
|
+
if (resolved !== value[i]) {
|
|
18
|
+
if (!copy) copy = [...value];
|
|
19
|
+
copy[i] = resolved;
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
return copy ?? value;
|
|
23
|
+
}
|
|
24
|
+
if (typeof (value as { ref?: unknown }).ref === 'string') {
|
|
25
|
+
const resolved = resolve(value as ProjectDocumentTarget & { ref: string });
|
|
26
|
+
if (resolved === null) {
|
|
27
|
+
issue('def', `node reference did not resolve: ${JSON.stringify(value)}`);
|
|
28
|
+
return undefined;
|
|
29
|
+
}
|
|
30
|
+
if (resolved !== undefined) return resolved;
|
|
31
|
+
}
|
|
32
|
+
let copy: Record<string, unknown> | null = null;
|
|
33
|
+
for (const [key, entry] of Object.entries(value)) {
|
|
34
|
+
const resolved = resolveDocumentNodeReferences(entry, resolve, issue);
|
|
35
|
+
if (resolved !== entry) {
|
|
36
|
+
if (!copy) copy = { ...(value as Record<string, unknown>) };
|
|
37
|
+
copy[key] = resolved;
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
return copy ?? value;
|
|
41
|
+
}
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
import type { GraphNode } from "../address.js";
|
|
2
|
+
import type { GltfAssociation } from "../loadedGltf.js";
|
|
3
|
+
import type { ProjectEvaluationIssue } from "./types.js";
|
|
4
|
+
|
|
5
|
+
/** Converts runtime vectors and rotations to and from document arrays. */
|
|
6
|
+
export interface DocumentVector {
|
|
7
|
+
fromArray(value: number[]): unknown;
|
|
8
|
+
toArray(): number[];
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
/** The scene operations used by composition, independent of a three.js build. */
|
|
12
|
+
export interface DocumentNode extends GraphNode {
|
|
13
|
+
name: string;
|
|
14
|
+
isObject3D: boolean;
|
|
15
|
+
userData: Record<string, unknown>;
|
|
16
|
+
parent: DocumentNode | null;
|
|
17
|
+
children: DocumentNode[];
|
|
18
|
+
position: DocumentVector;
|
|
19
|
+
quaternion: DocumentVector;
|
|
20
|
+
scale: DocumentVector;
|
|
21
|
+
add(...nodes: DocumentNode[]): unknown;
|
|
22
|
+
removeFromParent(): unknown;
|
|
23
|
+
traverse(visitor: (node: DocumentNode) => void): void;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** Loaded asset scenes and metadata used to resolve document targets. */
|
|
27
|
+
export interface DocumentModel {
|
|
28
|
+
/** Default scene used as the template for document references. */
|
|
29
|
+
scene?: DocumentNode;
|
|
30
|
+
/** Loaded scenes used when attaching stable node IDs from glTF metadata. */
|
|
31
|
+
scenes?: DocumentNode[];
|
|
32
|
+
/** Loaded clips available for address resolution; loading does not play them. */
|
|
33
|
+
animations?: object[];
|
|
34
|
+
/** Optional glTF loader metadata used to resolve asset objects and materials. */
|
|
35
|
+
parser?: {
|
|
36
|
+
/** Source glTF data used for stable node IDs and material lookup. */
|
|
37
|
+
json?: Record<string, unknown> & { materials?: Array<{ name?: string }> };
|
|
38
|
+
/** Maps loaded objects to their source glTF indices. */
|
|
39
|
+
associations?: Map<object, GltfAssociation>;
|
|
40
|
+
/** Loads a source resource by kind and index; used here for materials. */
|
|
41
|
+
getDependency?(type: string, index: number): Promise<unknown>;
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** Reports which document operation could not be applied and why. */
|
|
46
|
+
export type DocumentIssueReporter = (arc: ProjectEvaluationIssue["arc"], message: string) => void;
|
|
47
|
+
|
|
48
|
+
/** Scene and component hooks used while applying document definitions. */
|
|
49
|
+
export interface DocumentDefContext {
|
|
50
|
+
/** Runtime scene available to definition readers. */
|
|
51
|
+
scene?: DocumentNode;
|
|
52
|
+
/** Creates an unattached node for a definition's `create` entry. */
|
|
53
|
+
createNode(): DocumentNode;
|
|
54
|
+
/** Legacy reader for component definitions without an extension owner. */
|
|
55
|
+
applyComponent?(node: DocumentNode, data: { name: string } & Record<string, unknown>, issue: (arc: "def", message: string) => void): void;
|
|
56
|
+
/** Readers for owned definitions, keyed by document extension ID. */
|
|
57
|
+
readonly extensions?: ReadonlyMap<string, DocumentExtensionProvider>;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** Reads one extension's saved data using the declared version and migrations. */
|
|
61
|
+
export interface DocumentExtensionProvider {
|
|
62
|
+
/** Current saved-data version understood by this reader. */
|
|
63
|
+
readonly version: number;
|
|
64
|
+
/** Typed property values supported by this extension version. */
|
|
65
|
+
readonly valueCodecs?: Readonly<Record<string, import('./valueCodecs.js').DocumentValueCodec>>;
|
|
66
|
+
/** Source version to migration function; each function produces the current format. */
|
|
67
|
+
readonly migrations?: Readonly<Record<number, (data: Record<string, unknown>) => Record<string, unknown>>>;
|
|
68
|
+
/** Omit when this extension cannot restore component data. */
|
|
69
|
+
readonly components?: {
|
|
70
|
+
/** Applies one component's resolved data to its target node. */
|
|
71
|
+
apply(node: DocumentNode, data: { name: string } & Record<string, unknown>, issue: (arc: "def", message: string) => void): void;
|
|
72
|
+
};
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** Host operations used by the shared evaluator to load assets and apply document data. */
|
|
76
|
+
export interface DocumentRuntime {
|
|
77
|
+
/** Default parent for composed document content. */
|
|
78
|
+
scene: DocumentNode;
|
|
79
|
+
/** Host renderer targeted by renderer property overrides. */
|
|
80
|
+
renderer: object;
|
|
81
|
+
/** Creates an unattached scene node. */
|
|
82
|
+
createNode(): DocumentNode;
|
|
83
|
+
/** Converts document color channels into the host's color value. */
|
|
84
|
+
createColor(value: number[]): object;
|
|
85
|
+
/** Parses asset data, using `src` as its identity and relative-resource base. */
|
|
86
|
+
parse(data: ArrayBuffer | string, src: string, options?: { resolveUrl(url: string): string }): Promise<DocumentModel | null>;
|
|
87
|
+
/** Creates a reference instance from a loaded template. */
|
|
88
|
+
clone(template: DocumentNode, referenceId: string): DocumentNode | null;
|
|
89
|
+
/** Keeps a loaded template inactive while reference instances are composed. */
|
|
90
|
+
parkTemplate(node: DocumentNode): void;
|
|
91
|
+
/** Enables a placed reference instance through the host's lifecycle. */
|
|
92
|
+
activateInstance(node: DocumentNode): void;
|
|
93
|
+
/** Releases a template after cloning without destroying its placed instances. */
|
|
94
|
+
disposeTemplate(node: DocumentNode): void;
|
|
95
|
+
/** Run after template deserialization, before any instance activates its components. */
|
|
96
|
+
schedule(work: () => void): void;
|
|
97
|
+
/** Loads the host's environment resource for a document environment URL. */
|
|
98
|
+
loadEnvironment(url: string, options: { format?: "pmrem"; name?: string }): Promise<object | null>;
|
|
99
|
+
/** Binds definition readers to the composed root and document URL. */
|
|
100
|
+
createDefContext?(root: DocumentNode, baseUrl?: string): DocumentDefContext;
|
|
101
|
+
/** Lists components attached to a node for component-target resolution. */
|
|
102
|
+
getComponents?(node: DocumentNode): object[];
|
|
103
|
+
/** Matches a component against its saved type name. */
|
|
104
|
+
matchesComponentType?(component: object, name: string): boolean;
|
|
105
|
+
/** Matches a component against its saved stable ID. */
|
|
106
|
+
matchesComponentGuid?(component: object, guid: string): boolean;
|
|
107
|
+
/** Derives an instance component ID from its reference and source-file IDs. */
|
|
108
|
+
deriveComponentGuid?(referenceId: string, fileGuid: string): string;
|
|
109
|
+
/** Removes a component through the host's lifecycle; owner may be unresolved. */
|
|
110
|
+
removeComponent?(component: object, owner: DocumentNode | null): void;
|
|
111
|
+
/** Identity used by the optional inspection registry; defaults to the runtime itself. */
|
|
112
|
+
inspectionOwner?: object;
|
|
113
|
+
}
|
|
@@ -0,0 +1,293 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "http://json-schema.org/draft-07/schema#",
|
|
3
|
+
"$id": "https://needle.tools/schemas/project-document-0.1.json",
|
|
4
|
+
"title": "Needle project document",
|
|
5
|
+
"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.",
|
|
6
|
+
"type": "object",
|
|
7
|
+
"required": ["needle:project"],
|
|
8
|
+
"properties": {
|
|
9
|
+
"needle:project": {
|
|
10
|
+
"type": "string",
|
|
11
|
+
"minLength": 1,
|
|
12
|
+
"description": "Format version discriminator. Its presence IS the document sniff (isProjectDocument / parseSync). Current: \"0.1\"."
|
|
13
|
+
},
|
|
14
|
+
"metadata": {
|
|
15
|
+
"type": "object",
|
|
16
|
+
"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."
|
|
17
|
+
},
|
|
18
|
+
"extensions": {
|
|
19
|
+
"type": "object",
|
|
20
|
+
"description": "Required document extensions. Declarations never authorize installing or executing extensions.",
|
|
21
|
+
"additionalProperties": {
|
|
22
|
+
"type": "object",
|
|
23
|
+
"required": ["version"],
|
|
24
|
+
"properties": {
|
|
25
|
+
"version": { "type": "integer", "minimum": 1 }
|
|
26
|
+
},
|
|
27
|
+
"additionalProperties": true
|
|
28
|
+
}
|
|
29
|
+
},
|
|
30
|
+
"assets": {
|
|
31
|
+
"type": "object",
|
|
32
|
+
"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).",
|
|
33
|
+
"additionalProperties": { "$ref": "#/definitions/asset" }
|
|
34
|
+
},
|
|
35
|
+
"remotes": {
|
|
36
|
+
"type": "object",
|
|
37
|
+
"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.",
|
|
38
|
+
"additionalProperties": { "type": "string" }
|
|
39
|
+
},
|
|
40
|
+
"references": {
|
|
41
|
+
"type": "array",
|
|
42
|
+
"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.",
|
|
43
|
+
"items": { "$ref": "#/definitions/reference" }
|
|
44
|
+
},
|
|
45
|
+
"bindings": {
|
|
46
|
+
"type": "array",
|
|
47
|
+
"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.",
|
|
48
|
+
"items": { "$ref": "#/definitions/binding" }
|
|
49
|
+
},
|
|
50
|
+
"defs": {
|
|
51
|
+
"type": "array",
|
|
52
|
+
"description": "Add components to nodes, and (with `create`) DEFINE new nodes.",
|
|
53
|
+
"items": { "$ref": "#/definitions/def" }
|
|
54
|
+
},
|
|
55
|
+
"overs": {
|
|
56
|
+
"type": "array",
|
|
57
|
+
"description": "Property patches on existing content. Applied in document order — later entries win on the same target.",
|
|
58
|
+
"items": { "$ref": "#/definitions/over" }
|
|
59
|
+
},
|
|
60
|
+
"meta": {
|
|
61
|
+
"not": {},
|
|
62
|
+
"description": "RETIRED — renamed to `metadata` (clean break, no compat shim). Present only to fail loudly if a writer regresses."
|
|
63
|
+
}
|
|
64
|
+
},
|
|
65
|
+
"additionalProperties": true,
|
|
66
|
+
|
|
67
|
+
"definitions": {
|
|
68
|
+
"binding": {
|
|
69
|
+
"type": "object",
|
|
70
|
+
"required": ["id", "kind", "signature"],
|
|
71
|
+
"properties": {
|
|
72
|
+
"id": { "type": "string", "minLength": 1, "description": "Document-local reference used by targets. `$`-prefixed ids are reserved." },
|
|
73
|
+
"kind": { "const": "scene" },
|
|
74
|
+
"signature": { "type": "string", "minLength": 1, "description": "Stable structural identity used by the host to match this root before applying edits." },
|
|
75
|
+
"name": { "type": "string", "description": "Informational label for diagnostics only; never used as identity." },
|
|
76
|
+
"references": { "type": "array", "items": { "type": "string", "minLength": 1 } }
|
|
77
|
+
},
|
|
78
|
+
"additionalProperties": true
|
|
79
|
+
},
|
|
80
|
+
"asset": {
|
|
81
|
+
"type": "object",
|
|
82
|
+
"required": ["src"],
|
|
83
|
+
"properties": {
|
|
84
|
+
"src": {
|
|
85
|
+
"type": "string",
|
|
86
|
+
"minLength": 1,
|
|
87
|
+
"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)."
|
|
88
|
+
},
|
|
89
|
+
"guid": {
|
|
90
|
+
"type": "string",
|
|
91
|
+
"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."
|
|
92
|
+
},
|
|
93
|
+
"asset": {
|
|
94
|
+
"type": "object",
|
|
95
|
+
"required": ["id"],
|
|
96
|
+
"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.",
|
|
97
|
+
"properties": {
|
|
98
|
+
"id": { "type": "string", "minLength": 1 },
|
|
99
|
+
"provider": {
|
|
100
|
+
"type": "string",
|
|
101
|
+
"description": "Provider key hint — lets a cold session route straight to the owning provider instead of probing."
|
|
102
|
+
}
|
|
103
|
+
},
|
|
104
|
+
"additionalProperties": true
|
|
105
|
+
},
|
|
106
|
+
"kind": {
|
|
107
|
+
"type": "string",
|
|
108
|
+
"enum": ["model", "material", "hdr", "texture", "image", "video", "audio", "code", "text", "document", "archive"],
|
|
109
|
+
"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."
|
|
110
|
+
},
|
|
111
|
+
"etag": {
|
|
112
|
+
"type": "string",
|
|
113
|
+
"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."
|
|
114
|
+
}
|
|
115
|
+
},
|
|
116
|
+
"additionalProperties": true
|
|
117
|
+
},
|
|
118
|
+
|
|
119
|
+
"reference": {
|
|
120
|
+
"type": "object",
|
|
121
|
+
"required": ["id", "asset"],
|
|
122
|
+
"properties": {
|
|
123
|
+
"id": {
|
|
124
|
+
"type": "string",
|
|
125
|
+
"minLength": 1,
|
|
126
|
+
"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)."
|
|
127
|
+
},
|
|
128
|
+
"asset": {
|
|
129
|
+
"type": "string",
|
|
130
|
+
"minLength": 1,
|
|
131
|
+
"description": "Key into the document's `assets` map."
|
|
132
|
+
},
|
|
133
|
+
"address": {
|
|
134
|
+
"$ref": "#/definitions/address",
|
|
135
|
+
"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\" })."
|
|
136
|
+
},
|
|
137
|
+
"parent": {
|
|
138
|
+
"not": {},
|
|
139
|
+
"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."
|
|
140
|
+
},
|
|
141
|
+
"transform": {
|
|
142
|
+
"not": {},
|
|
143
|
+
"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."
|
|
144
|
+
}
|
|
145
|
+
},
|
|
146
|
+
"additionalProperties": true
|
|
147
|
+
},
|
|
148
|
+
|
|
149
|
+
"def": {
|
|
150
|
+
"type": "object",
|
|
151
|
+
"required": ["target"],
|
|
152
|
+
"anyOf": [
|
|
153
|
+
{ "required": ["create"] },
|
|
154
|
+
{ "required": ["components"] }
|
|
155
|
+
],
|
|
156
|
+
"properties": {
|
|
157
|
+
"target": { "$ref": "#/definitions/target" },
|
|
158
|
+
"extension": { "type": "string", "minLength": 1, "description": "Key in extensions; owns every component in this def. Omit for legacy definitions." },
|
|
159
|
+
"create": {
|
|
160
|
+
"type": "object",
|
|
161
|
+
"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.",
|
|
162
|
+
"properties": {
|
|
163
|
+
"id": { "type": "string", "minLength": 1, "description": "Stable needle-id assigned to the created node." },
|
|
164
|
+
"name": { "type": "string" },
|
|
165
|
+
"position": { "type": "array", "items": { "type": "number" }, "minItems": 3 },
|
|
166
|
+
"quaternion": { "type": "array", "items": { "type": "number" }, "minItems": 4 },
|
|
167
|
+
"scale": { "type": "array", "items": { "type": "number" }, "minItems": 3 },
|
|
168
|
+
"copy": {
|
|
169
|
+
"type": "object",
|
|
170
|
+
"description": "Recreate a hierarchy duplicate from an addressed source. The seed reproduces the hierarchy identities. Entries sharing batch are cloned together in index order.",
|
|
171
|
+
"required": ["source", "seed"],
|
|
172
|
+
"anyOf": [
|
|
173
|
+
{ "required": ["batch", "index"] },
|
|
174
|
+
{
|
|
175
|
+
"allOf": [
|
|
176
|
+
{ "not": { "required": ["batch"] } },
|
|
177
|
+
{ "not": { "required": ["index"] } }
|
|
178
|
+
]
|
|
179
|
+
}
|
|
180
|
+
],
|
|
181
|
+
"properties": {
|
|
182
|
+
"source": { "$ref": "#/definitions/target" },
|
|
183
|
+
"seed": { "type": "string", "minLength": 1 },
|
|
184
|
+
"reference": { "type": "boolean" },
|
|
185
|
+
"batch": { "type": "string", "minLength": 1 },
|
|
186
|
+
"index": { "type": "integer" }
|
|
187
|
+
},
|
|
188
|
+
"additionalProperties": true
|
|
189
|
+
}
|
|
190
|
+
},
|
|
191
|
+
"additionalProperties": true
|
|
192
|
+
},
|
|
193
|
+
"components": {
|
|
194
|
+
"type": "array",
|
|
195
|
+
"description": "VERBATIM NEEDLE_components wire entries — no parallel vocabulary. Unknown component types are reported and skipped.",
|
|
196
|
+
"items": {
|
|
197
|
+
"type": "object",
|
|
198
|
+
"required": ["name"],
|
|
199
|
+
"properties": {
|
|
200
|
+
"name": {
|
|
201
|
+
"type": "string",
|
|
202
|
+
"minLength": 1,
|
|
203
|
+
"description": "TypeStore name. NOTE: runtime constructor names are decorator-wrapped (\"_DragControls\") — match by guid, not by ctor name."
|
|
204
|
+
},
|
|
205
|
+
"guid": { "type": "string" }
|
|
206
|
+
},
|
|
207
|
+
"additionalProperties": true
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
},
|
|
211
|
+
"additionalProperties": true
|
|
212
|
+
},
|
|
213
|
+
|
|
214
|
+
"extensionValue": {
|
|
215
|
+
"type": "object",
|
|
216
|
+
"description": "Versioned extension-owned property data. Missing or incompatible decoders report an issue and preserve the payload; runtime objects and executable functions are never stored.",
|
|
217
|
+
"required": ["$extension", "type", "version", "data"],
|
|
218
|
+
"properties": {
|
|
219
|
+
"$extension": { "type": "string", "minLength": 1 },
|
|
220
|
+
"type": { "type": "string", "minLength": 1 },
|
|
221
|
+
"version": { "type": "integer", "minimum": 1 },
|
|
222
|
+
"data": {}
|
|
223
|
+
},
|
|
224
|
+
"additionalProperties": true
|
|
225
|
+
},
|
|
226
|
+
|
|
227
|
+
"over": {
|
|
228
|
+
"type": "object",
|
|
229
|
+
"required": ["target", "value"],
|
|
230
|
+
"properties": {
|
|
231
|
+
"target": { "$ref": "#/definitions/overTarget" },
|
|
232
|
+
"value": {
|
|
233
|
+
"anyOf": [
|
|
234
|
+
{ "not": { "type": "object", "required": ["$extension"] } },
|
|
235
|
+
{ "$ref": "#/definitions/extensionValue" }
|
|
236
|
+
],
|
|
237
|
+
"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."
|
|
238
|
+
}
|
|
239
|
+
},
|
|
240
|
+
"additionalProperties": true
|
|
241
|
+
},
|
|
242
|
+
|
|
243
|
+
"target": {
|
|
244
|
+
"type": "object",
|
|
245
|
+
"description": "Where an arc applies. `ref` selects the resolution scope; `address` locates an element inside it; `component` selects a component on the resolved node.",
|
|
246
|
+
"properties": {
|
|
247
|
+
"ref": {
|
|
248
|
+
"type": "string",
|
|
249
|
+
"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)."
|
|
250
|
+
},
|
|
251
|
+
"address": { "$ref": "#/definitions/address" },
|
|
252
|
+
"component": {
|
|
253
|
+
"not": {},
|
|
254
|
+
"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."
|
|
255
|
+
},
|
|
256
|
+
"path": {
|
|
257
|
+
"type": "string",
|
|
258
|
+
"minLength": 1,
|
|
259
|
+
"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)."
|
|
260
|
+
}
|
|
261
|
+
},
|
|
262
|
+
"additionalProperties": true
|
|
263
|
+
},
|
|
264
|
+
|
|
265
|
+
"overTarget": {
|
|
266
|
+
"allOf": [
|
|
267
|
+
{ "$ref": "#/definitions/target" },
|
|
268
|
+
{
|
|
269
|
+
"type": "object",
|
|
270
|
+
"required": ["path"],
|
|
271
|
+
"description": "An over without a target path is reported and skipped by the evaluator."
|
|
272
|
+
}
|
|
273
|
+
]
|
|
274
|
+
},
|
|
275
|
+
|
|
276
|
+
"address": {
|
|
277
|
+
"type": "object",
|
|
278
|
+
"description": "Fat address (@needle-tools/addressing). Resolution ladder: id → anchor → path. Recording several identifiers is the point — content changes underneath live edits.",
|
|
279
|
+
"properties": {
|
|
280
|
+
"type": {
|
|
281
|
+
"type": "string",
|
|
282
|
+
"description": "Element kind, e.g. \"node\" | \"material\" | \"mesh\" | \"hdr\". Materials resolve against the scope's meshes (id → name), not the graph."
|
|
283
|
+
},
|
|
284
|
+
"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)." },
|
|
285
|
+
"name": { "type": "string" },
|
|
286
|
+
"anchor": { "type": "string" },
|
|
287
|
+
"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." },
|
|
288
|
+
"index": { "type": "integer", "description": "Weakest, reorder-fragile positional fallback." }
|
|
289
|
+
},
|
|
290
|
+
"additionalProperties": true
|
|
291
|
+
}
|
|
292
|
+
}
|
|
293
|
+
}
|