@aura3d/editor-runtime 1.0.6

package/src/PrefabRegistry.ts

@@ -0,0 +1,164 @@
+export type EditorPrefabSchemaVersion = "aura3d-prefab";
+
+export interface EditorPrefabNodeBase {
+  readonly id: string;
+  readonly name: string;
+  readonly parentId: string | null;
+}
+
+export interface EditorPrefab<TNode extends EditorPrefabNodeBase = EditorPrefabNodeBase> {
+  readonly schemaVersion: EditorPrefabSchemaVersion;
+  readonly id: string;
+  readonly name: string;
+  readonly rootNodeId: string;
+  readonly sourceNodeId?: string;
+  readonly createdAt: string;
+  readonly nodes: readonly TNode[];
+}
+
+export interface CreatePrefabOptions<TNode extends EditorPrefabNodeBase> {
+  readonly id: string;
+  readonly name: string;
+  readonly rootNodeId: string;
+  readonly sourceNodeId?: string;
+  readonly createdAt?: string;
+  readonly nodes: readonly TNode[];
+}
+
+export interface InstantiatePrefabOptions {
+  readonly idPrefix: string;
+  readonly rootParentId?: string | null;
+  readonly nameSuffix?: string;
+}
+
+export class PrefabRegistry<TNode extends EditorPrefabNodeBase = EditorPrefabNodeBase> {
+  private readonly prefabsById = new Map<string, EditorPrefab<TNode>>();
+
+  create(options: CreatePrefabOptions<TNode>): EditorPrefab<TNode> {
+    const prefab: EditorPrefab<TNode> = {
+      schemaVersion: "aura3d-prefab",
+      id: normalizeId(options.id, "prefab id"),
+      name: normalizeName(options.name, "prefab name"),
+      rootNodeId: normalizeId(options.rootNodeId, "prefab rootNodeId"),
+      ...(options.sourceNodeId ? { sourceNodeId: normalizeId(options.sourceNodeId, "prefab sourceNodeId") } : {}),
+      createdAt: options.createdAt ?? new Date().toISOString(),
+      nodes: options.nodes.map((node) => cloneNode(node))
+    };
+    validatePrefab(prefab);
+    return prefab;
+  }
+
+  register(prefab: EditorPrefab<TNode>): EditorPrefab<TNode> {
+    validatePrefab(prefab);
+    if (this.prefabsById.has(prefab.id)) {
+      throw new Error(`Prefab already registered: ${prefab.id}`);
+    }
+    const cloned = clonePrefab(prefab);
+    this.prefabsById.set(cloned.id, cloned);
+    return cloned;
+  }
+
+  upsert(prefab: EditorPrefab<TNode>): EditorPrefab<TNode> {
+    validatePrefab(prefab);
+    const cloned = clonePrefab(prefab);
+    this.prefabsById.set(cloned.id, cloned);
+    return cloned;
+  }
+
+  get(id: string): EditorPrefab<TNode> | undefined {
+    const prefab = this.prefabsById.get(id);
+    return prefab ? clonePrefab(prefab) : undefined;
+  }
+
+  list(): readonly EditorPrefab<TNode>[] {
+    return [...this.prefabsById.values()].map((prefab) => clonePrefab(prefab));
+  }
+
+  remove(id: string): boolean {
+    return this.prefabsById.delete(id);
+  }
+
+  clear(): void {
+    this.prefabsById.clear();
+  }
+
+  instantiate(prefabOrId: EditorPrefab<TNode> | string, options: InstantiatePrefabOptions): readonly TNode[] {
+    const prefab = typeof prefabOrId === "string" ? this.get(prefabOrId) : clonePrefab(prefabOrId);
+    if (!prefab) {
+      throw new Error(`Unknown prefab: ${prefabOrId}`);
+    }
+    validatePrefab(prefab);
+    const idPrefix = normalizeId(options.idPrefix, "prefab instance idPrefix");
+    const idMap = new Map(prefab.nodes.map((node) => [node.id, `${idPrefix}-${node.id}`]));
+    const rootParentId = options.rootParentId ?? null;
+    const nameSuffix = options.nameSuffix ?? " Instance";
+    return prefab.nodes.map((node) => {
+      const cloned = cloneNode(node);
+      const remappedParent = node.id === prefab.rootNodeId
+        ? rootParentId
+        : node.parentId ? idMap.get(node.parentId) ?? null : null;
+      return {
+        ...cloned,
+        id: idMap.get(node.id)!,
+        name: `${node.name}${nameSuffix}`,
+        parentId: remappedParent
+      };
+    });
+  }
+}
+
+export function validatePrefab<TNode extends EditorPrefabNodeBase>(prefab: EditorPrefab<TNode>): void {
+  if (prefab.schemaVersion !== "aura3d-prefab") {
+    throw new Error(`Unsupported prefab schemaVersion: ${String(prefab.schemaVersion)}`);
+  }
+  normalizeId(prefab.id, "prefab id");
+  normalizeName(prefab.name, "prefab name");
+  normalizeId(prefab.rootNodeId, "prefab rootNodeId");
+  if (prefab.nodes.length === 0) {
+    throw new Error("Prefab must contain at least one node.");
+  }
+  const ids = new Set<string>();
+  for (const node of prefab.nodes) {
+    normalizeId(node.id, "prefab node id");
+    normalizeName(node.name, "prefab node name");
+    if (ids.has(node.id)) {
+      throw new Error(`Prefab node id is duplicated: ${node.id}`);
+    }
+    ids.add(node.id);
+  }
+  if (!ids.has(prefab.rootNodeId)) {
+    throw new Error(`Prefab rootNodeId ${prefab.rootNodeId} is not present in nodes.`);
+  }
+  for (const node of prefab.nodes) {
+    if (node.parentId !== null && !ids.has(node.parentId)) {
+      throw new Error(`Prefab node ${node.id} references external parent ${node.parentId}`);
+    }
+  }
+}
+
+function clonePrefab<TNode extends EditorPrefabNodeBase>(prefab: EditorPrefab<TNode>): EditorPrefab<TNode> {
+  return {
+    ...prefab,
+    nodes: prefab.nodes.map((node) => cloneNode(node))
+  };
+}
+
+function cloneNode<TNode extends EditorPrefabNodeBase>(node: TNode): TNode {
+  return JSON.parse(JSON.stringify(node)) as TNode;
+}
+
+function normalizeId(value: string, label: string): string {
+  const normalized = value.trim();
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(normalized)) {
+    throw new Error(`${label} must be a non-empty stable id.`);
+  }
+  return normalized;
+}
+
+function normalizeName(value: string, label: string): string {
+  const normalized = value.trim();
+  if (normalized.length === 0) {
+    throw new Error(`${label} cannot be empty.`);
+  }
+  return normalized;
+}

package/src/ProjectSerializer.ts

@@ -0,0 +1,200 @@
+import { TimelineModel, type TimelineModelConfig } from "./TimelineModel";
+import type { TimelineRuntimeBindingConfig } from "./TimelineRuntimeBridge";
+
+export interface EditorProjectAssetDocument {
+  readonly id: string;
+  readonly name: string;
+  readonly uri?: string;
+  readonly type?: "gltf" | "glb" | "image" | "audio" | "material" | "unknown";
+  readonly source?: string;
+  readonly license?: string;
+  readonly clips?: readonly string[];
+  readonly morphTargets?: readonly string[];
+  readonly diagnostics?: readonly string[];
+}
+
+export interface EditorProjectTimelineDocument extends TimelineModelConfig {
+  readonly bindings?: readonly TimelineRuntimeBindingConfig[];
+  readonly evidence?: {
+    readonly authoredInEditor?: boolean;
+    readonly runtimeReplay?: boolean;
+    readonly animationEvents?: boolean;
+  };
+}
+
+export interface EditorProjectVisualGraphDocument {
+  readonly id: string;
+  readonly name: string;
+  readonly nodes: readonly unknown[];
+  readonly edges: readonly unknown[];
+  readonly runtimeBindings?: readonly {
+    readonly nodeId: string;
+    readonly targetId: string;
+    readonly event?: string;
+  }[];
+}
+
+export interface EditorProjectStateDocument {
+  readonly selectedNodeId?: string | number | null;
+  readonly activeTool?: string;
+  readonly activeTimelineId?: string | null;
+  readonly playMode?: "edit" | "play" | "paused";
+}
+
+export interface EditorProjectDocument {
+  readonly schema: "a3d-editor-project";
+  readonly version?: number;
+  readonly name: string;
+  readonly nodes: readonly unknown[];
+  readonly assets?: readonly (string | EditorProjectAssetDocument)[];
+  readonly timelines?: readonly EditorProjectTimelineDocument[];
+  readonly visualGraphs?: readonly EditorProjectVisualGraphDocument[];
+  readonly editor?: EditorProjectStateDocument;
+  readonly evidence?: {
+    readonly serializedBy?: "editor-runtime" | "editor-app" | string;
+    readonly roundTripReady?: boolean;
+    readonly browserWorkflowReady?: boolean;
+  };
+}
+
+export interface EditorProjectEvidence {
+  readonly kind: "aura-editor-project-evidence";
+  readonly schema: EditorProjectDocument["schema"];
+  readonly version: number | null;
+  readonly name: string;
+  readonly nodeCount: number;
+  readonly assetCount: number;
+  readonly timelineCount: number;
+  readonly visualGraphCount: number;
+  readonly timelineBindingCount: number;
+  readonly signalMarkerCount: number;
+  readonly typedAssetEvidenceCount: number;
+  readonly hasAnimationTimeline: boolean;
+  readonly hasRuntimeReplayBindings: boolean;
+  readonly hasVisualGraphBindings: boolean;
+  readonly roundTripReady: boolean;
+  readonly evidence: {
+    readonly projectSerialization: true;
+    readonly timelineSerialization: boolean;
+    readonly visualGraphSerialization: boolean;
+    readonly runtimeReplayBindings: boolean;
+    readonly sourceLicenseAssetEvidence: boolean;
+  };
+}
+
+export function serializeEditorProject(project: EditorProjectDocument): string {
+  const normalized = validateEditorProject(project);
+  return `${JSON.stringify(normalized, null, 2)}\n`;
+}
+
+export function parseEditorProject(text: string): EditorProjectDocument {
+  const parsed = JSON.parse(text) as EditorProjectDocument;
+  return validateEditorProject(parsed);
+}
+
+export function validateEditorProject(project: EditorProjectDocument): EditorProjectDocument {
+  if (!isRecord(project)) throw new Error("Editor project document must be an object.");
+  if (project.schema !== "a3d-editor-project") throw new Error("Unsupported editor project schema.");
+  if (typeof project.name !== "string" || !project.name.trim()) throw new Error("Editor project name is required.");
+  if (!Array.isArray(project.nodes)) throw new Error("Editor project nodes must be an array.");
+  validateAssets(project.assets ?? []);
+  validateTimelines(project.timelines ?? []);
+  validateVisualGraphs(project.visualGraphs ?? []);
+  return project;
+}
+
+export function collectEditorProjectEvidence(project: EditorProjectDocument): EditorProjectEvidence {
+  const parsed = validateEditorProject(project);
+  const timelines = parsed.timelines ?? [];
+  const visualGraphs = parsed.visualGraphs ?? [];
+  const timelineBindingCount = timelines.reduce((total, timeline) => total + (timeline.bindings?.length ?? 0), 0);
+  const signalMarkerCount = timelines.reduce((total, timeline) => {
+    return total + (timeline.tracks ?? []).reduce((trackTotal, track) => {
+      if (track.type !== "signal") return trackTotal;
+      return trackTotal + (track.clips?.length ?? 0);
+    }, 0);
+  }, 0);
+  const typedAssetEvidenceCount = (parsed.assets ?? []).filter((asset) => {
+    return typeof asset !== "string" && Boolean(asset.id && asset.name && asset.source && asset.license);
+  }).length;
+  const assetCount = parsed.assets?.length ?? 0;
+  const hasAnimationTimeline = timelines.some((timeline) => (timeline.tracks ?? []).some((track) => track.type === "animation"));
+  const hasVisualGraphBindings = visualGraphs.some((graph) => (graph.runtimeBindings?.length ?? 0) > 0);
+  const hasRuntimeReplayBindings = timelineBindingCount > 0;
+  return {
+    kind: "aura-editor-project-evidence",
+    schema: parsed.schema,
+    version: parsed.version ?? null,
+    name: parsed.name,
+    nodeCount: parsed.nodes.length,
+    assetCount,
+    timelineCount: timelines.length,
+    visualGraphCount: visualGraphs.length,
+    timelineBindingCount,
+    signalMarkerCount,
+    typedAssetEvidenceCount,
+    hasAnimationTimeline,
+    hasRuntimeReplayBindings,
+    hasVisualGraphBindings,
+    roundTripReady: parsed.nodes.length > 0 && timelines.length > 0 && hasRuntimeReplayBindings,
+    evidence: {
+      projectSerialization: true,
+      timelineSerialization: timelines.length > 0,
+      visualGraphSerialization: visualGraphs.length > 0,
+      runtimeReplayBindings: hasRuntimeReplayBindings || hasVisualGraphBindings,
+      sourceLicenseAssetEvidence: assetCount > 0 && typedAssetEvidenceCount === assetCount
+    }
+  };
+}
+
+function validateAssets(assets: readonly (string | EditorProjectAssetDocument)[]): void {
+  if (!Array.isArray(assets)) throw new Error("Editor project assets must be an array.");
+  for (const asset of assets) {
+    if (typeof asset === "string") {
+      if (!asset.trim()) throw new Error("Editor project asset ids must be non-empty.");
+      continue;
+    }
+    if (!asset.id.trim()) throw new Error("Editor project asset id is required.");
+    if (!asset.name.trim()) throw new Error(`Editor project asset name is required: ${asset.id}`);
+    assertStringArray(asset.clips, `asset clips for ${asset.id}`);
+    assertStringArray(asset.morphTargets, `asset morphTargets for ${asset.id}`);
+    assertStringArray(asset.diagnostics, `asset diagnostics for ${asset.id}`);
+  }
+}
+
+function validateTimelines(timelines: readonly EditorProjectTimelineDocument[]): void {
+  if (!Array.isArray(timelines)) throw new Error("Editor project timelines must be an array.");
+  for (const timeline of timelines) {
+    new TimelineModel(timeline);
+    for (const binding of timeline.bindings ?? []) {
+      if (!binding.targetId.trim()) throw new Error(`Timeline binding targetId is required for timeline ${timeline.id ?? timeline.name ?? "unnamed"}.`);
+      if (binding.trackId !== undefined && !binding.trackId.trim()) throw new Error("Timeline binding trackId cannot be empty.");
+      if (binding.trackName !== undefined && !binding.trackName.trim()) throw new Error("Timeline binding trackName cannot be empty.");
+    }
+  }
+}
+
+function validateVisualGraphs(graphs: readonly EditorProjectVisualGraphDocument[]): void {
+  if (!Array.isArray(graphs)) throw new Error("Editor project visualGraphs must be an array.");
+  for (const graph of graphs) {
+    if (!graph.id.trim()) throw new Error("Editor project visual graph id is required.");
+    if (!graph.name.trim()) throw new Error(`Editor project visual graph name is required: ${graph.id}`);
+    if (!Array.isArray(graph.nodes)) throw new Error(`Editor project visual graph nodes must be an array: ${graph.id}`);
+    if (!Array.isArray(graph.edges)) throw new Error(`Editor project visual graph edges must be an array: ${graph.id}`);
+    for (const binding of graph.runtimeBindings ?? []) {
+      if (!binding.nodeId.trim()) throw new Error(`Visual graph runtime binding nodeId is required: ${graph.id}`);
+      if (!binding.targetId.trim()) throw new Error(`Visual graph runtime binding targetId is required: ${graph.id}`);
+    }
+  }
+}
+
+function assertStringArray(values: readonly string[] | undefined, label: string): void {
+  if (values === undefined) return;
+  if (!Array.isArray(values) || values.some((value) => !value.trim())) {
+    throw new Error(`Editor project ${label} must be non-empty strings.`);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/src/RotateGizmo.ts

@@ -0,0 +1,35 @@
+import { Gizmo, type GizmoDrag } from "./Gizmo";
+import { TransformCommand, type TransformLike } from "./commands/TransformCommand";
+
+export class RotateGizmo extends Gizmo {
+  async drag(input: GizmoDrag): Promise<void> {
+    if (!this.target) return;
+    const current = readTransform(this.target);
+    const next = clone(current);
+    next.rotation ??= { x: 0, y: 0, z: 0, w: 1 };
+    const delta = this.snapRotationDelta(input.delta);
+    if (input.axis === "x") next.rotation.x += delta;
+    if (input.axis === "y") next.rotation.y += delta;
+    if (input.axis === "z" || input.axis === "uniform") next.rotation.z += delta;
+    await this.history.execute(new TransformCommand(this.target, next));
+  }
+}
+
+function readTransform(target: NonNullable<RotateGizmo["target"]>): TransformLike {
+  if ("transform" in target) {
+    return {
+      position: { x: target.transform.position[0], y: target.transform.position[1], z: target.transform.position[2] },
+      rotation: { x: target.transform.rotation[0], y: target.transform.rotation[1], z: target.transform.rotation[2], w: target.transform.rotation[3] },
+      scale: { x: target.transform.scale[0], y: target.transform.scale[1], z: target.transform.scale[2] }
+    };
+  }
+  return clone(target);
+}
+
+function clone(transform: TransformLike): TransformLike {
+  return {
+    position: { ...transform.position },
+    rotation: transform.rotation ? { ...transform.rotation } : undefined,
+    scale: transform.scale ? { ...transform.scale } : undefined
+  };
+}

package/src/ScaleGizmo.ts

@@ -0,0 +1,40 @@
+import { Gizmo, type GizmoDrag } from "./Gizmo";
+import { TransformCommand, type TransformLike } from "./commands/TransformCommand";
+
+export class ScaleGizmo extends Gizmo {
+  async drag(input: GizmoDrag): Promise<void> {
+    if (!this.target) return;
+    const current = readTransform(this.target);
+    const next = clone(current);
+    next.scale ??= { x: 1, y: 1, z: 1 };
+    const amount = Math.max(0.001, this.snapScaleFactor(1 + input.delta));
+    if (input.axis === "x") next.scale.x *= amount;
+    if (input.axis === "y") next.scale.y *= amount;
+    if (input.axis === "z") next.scale.z *= amount;
+    if (input.axis === "uniform") {
+      next.scale.x *= amount;
+      next.scale.y *= amount;
+      next.scale.z *= amount;
+    }
+    await this.history.execute(new TransformCommand(this.target, next));
+  }
+}
+
+function readTransform(target: NonNullable<ScaleGizmo["target"]>): TransformLike {
+  if ("transform" in target) {
+    return {
+      position: { x: target.transform.position[0], y: target.transform.position[1], z: target.transform.position[2] },
+      rotation: { x: target.transform.rotation[0], y: target.transform.rotation[1], z: target.transform.rotation[2], w: target.transform.rotation[3] },
+      scale: { x: target.transform.scale[0], y: target.transform.scale[1], z: target.transform.scale[2] }
+    };
+  }
+  return clone(target);
+}
+
+function clone(transform: TransformLike): TransformLike {
+  return {
+    position: { ...transform.position },
+    rotation: transform.rotation ? { ...transform.rotation } : undefined,
+    scale: transform.scale ? { ...transform.scale } : undefined
+  };
+}

package/src/Selection.ts

@@ -0,0 +1,63 @@
+export type SelectionId = string | number;
+
+export interface SelectionChange {
+  readonly previous: readonly SelectionId[];
+  readonly current: readonly SelectionId[];
+}
+
+export type SelectionListener = (change: SelectionChange) => void;
+
+export class Selection {
+  private readonly ids = new Set<SelectionId>();
+  private readonly listeners = new Set<SelectionListener>();
+
+  current(): readonly SelectionId[] {
+    return [...this.ids];
+  }
+
+  has(id: SelectionId): boolean {
+    return this.ids.has(id);
+  }
+
+  set(ids: readonly SelectionId[]): void {
+    this.replace(new Set(ids));
+  }
+
+  add(id: SelectionId): void {
+    this.replace(new Set([...this.ids, id]));
+  }
+
+  remove(id: SelectionId): void {
+    const next = new Set(this.ids);
+    next.delete(id);
+    this.replace(next);
+  }
+
+  clear(): void {
+    this.replace(new Set());
+  }
+
+  subscribe(listener: SelectionListener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  prune(alive: (id: SelectionId) => boolean): void {
+    this.replace(new Set([...this.ids].filter(alive)));
+  }
+
+  private replace(next: Set<SelectionId>): void {
+    const previous = this.current();
+    this.ids.clear();
+    for (const id of next) {
+      this.ids.add(id);
+    }
+    const current = this.current();
+    if (previous.length !== current.length || previous.some((id, index) => id !== current[index])) {
+      const change = { previous, current };
+      for (const listener of [...this.listeners]) {
+        listener(change);
+      }
+    }
+  }
+}