auto-git:

[add] .prettierrc.json
 [add] eslint.config.js
 [add] index.html
 [add] package.json
 [add] playwright.config.ts
 [add] src/app/App.tsx
 [add] src/app/app.css
 [add] src/app/editor-store.ts
 [add] src/app/use-editor-store.ts
 [add] src/assets/.gitkeep
 [add] src/commands/command-history.ts
 [add] src/commands/command.ts
 [add] src/commands/set-scene-name-command.ts
 [add] src/core/ids.ts
 [add] src/core/selection.ts
 [add] src/core/tool-mode.ts
 [add] src/core/vector.ts
 [add] src/document/migrate-scene-document.ts
 [add] src/document/scene-document.ts
 [add] src/entities/.gitkeep
 [add] src/geometry/.gitkeep
 [add] src/main.tsx
 [add] src/materials/.gitkeep
 [add] src/runtime-three/.gitkeep
 [add] src/serialization/local-draft-storage.ts
 [add] src/serialization/scene-document-json.ts
 [add] src/shared-ui/Panel.tsx
 [add] src/viewport-three/ViewportCanvas.tsx
 [add] src/viewport-three/viewport-host.ts
 [add] src/vite-env.d.ts
 [add] tests/domain/create-empty-scene-document.test.ts
 [add] tests/domain/editor-store.test.ts
 [add] tests/e2e/app-smoke.e2e.ts
 [add] tests/serialization/scene-document-json.test.ts
 [add] tests/setup/vitest.setup.ts
 [add] tsconfig.json
 [add] vite.config.ts
 [add] vitest.config.ts

src/document/migrate-scene-document.ts

@@ -0,0 +1,114 @@
+import { SCENE_DOCUMENT_VERSION, type SceneDocument, type WorldSettings } from "./scene-document";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function expectFiniteNumber(value: unknown, label: string): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`${label} must be a finite number.`);
+  }
+
+  return value;
+}
+
+function expectString(value: unknown, label: string): string {
+  if (typeof value !== "string") {
+    throw new Error(`${label} must be a string.`);
+  }
+
+  return value;
+}
+
+function expectHexColor(value: unknown, label: string): string {
+  const normalizedValue = expectString(value, label);
+
+  if (!/^#[0-9a-f]{6}$/i.test(normalizedValue)) {
+    throw new Error(`${label} must use #RRGGBB format.`);
+  }
+
+  return normalizedValue;
+}
+
+function expectEmptyCollection(value: unknown, label: string): Record<string, never> {
+  if (!isRecord(value)) {
+    throw new Error(`${label} must be a record.`);
+  }
+
+  if (Object.keys(value).length > 0) {
+    throw new Error(`${label} must be empty in the foundation schema.`);
+  }
+
+  return {};
+}
+
+function readWorldSettings(value: unknown): WorldSettings {
+  if (!isRecord(value)) {
+    throw new Error("world must be an object.");
+  }
+
+  const background = value.background;
+  const ambientLight = value.ambientLight;
+  const sunLight = value.sunLight;
+
+  if (!isRecord(background)) {
+    throw new Error("world.background must be an object.");
+  }
+
+  if (!isRecord(ambientLight)) {
+    throw new Error("world.ambientLight must be an object.");
+  }
+
+  if (!isRecord(sunLight)) {
+    throw new Error("world.sunLight must be an object.");
+  }
+
+  const direction = sunLight.direction;
+
+  if (!isRecord(direction)) {
+    throw new Error("world.sunLight.direction must be an object.");
+  }
+
+  return {
+    background: {
+      mode: "solid",
+      colorHex: expectHexColor(background.colorHex, "world.background.colorHex")
+    },
+    ambientLight: {
+      colorHex: expectHexColor(ambientLight.colorHex, "world.ambientLight.colorHex"),
+      intensity: expectFiniteNumber(ambientLight.intensity, "world.ambientLight.intensity")
+    },
+    sunLight: {
+      colorHex: expectHexColor(sunLight.colorHex, "world.sunLight.colorHex"),
+      intensity: expectFiniteNumber(sunLight.intensity, "world.sunLight.intensity"),
+      direction: {
+        x: expectFiniteNumber(direction.x, "world.sunLight.direction.x"),
+        y: expectFiniteNumber(direction.y, "world.sunLight.direction.y"),
+        z: expectFiniteNumber(direction.z, "world.sunLight.direction.z")
+      }
+    }
+  };
+}
+
+export function migrateSceneDocument(source: unknown): SceneDocument {
+  if (!isRecord(source)) {
+    throw new Error("Scene document must be a JSON object.");
+  }
+
+  if (source.version !== SCENE_DOCUMENT_VERSION) {
+    throw new Error(`Unsupported scene document version: ${String(source.version)}.`);
+  }
+
+  return {
+    version: SCENE_DOCUMENT_VERSION,
+    name: expectString(source.name, "name"),
+    world: readWorldSettings(source.world),
+    materials: expectEmptyCollection(source.materials, "materials"),
+    textures: expectEmptyCollection(source.textures, "textures"),
+    assets: expectEmptyCollection(source.assets, "assets"),
+    brushes: expectEmptyCollection(source.brushes, "brushes"),
+    modelInstances: expectEmptyCollection(source.modelInstances, "modelInstances"),
+    entities: expectEmptyCollection(source.entities, "entities"),
+    interactionLinks: expectEmptyCollection(source.interactionLinks, "interactionLinks")
+  };
+}

src/document/scene-document.ts

@@ -0,0 +1,71 @@
+import { DEFAULT_SUN_DIRECTION, type Vec3 } from "../core/vector";
+
+export const SCENE_DOCUMENT_VERSION = 1 as const;
+
+export interface WorldBackgroundSettings {
+  mode: "solid";
+  colorHex: string;
+}
+
+export interface WorldAmbientLightSettings {
+  colorHex: string;
+  intensity: number;
+}
+
+export interface WorldSunLightSettings {
+  colorHex: string;
+  intensity: number;
+  direction: Vec3;
+}
+
+export interface WorldSettings {
+  background: WorldBackgroundSettings;
+  ambientLight: WorldAmbientLightSettings;
+  sunLight: WorldSunLightSettings;
+}
+
+export interface SceneDocument {
+  version: typeof SCENE_DOCUMENT_VERSION;
+  name: string;
+  world: WorldSettings;
+  materials: Record<string, never>;
+  textures: Record<string, never>;
+  assets: Record<string, never>;
+  brushes: Record<string, never>;
+  modelInstances: Record<string, never>;
+  entities: Record<string, never>;
+  interactionLinks: Record<string, never>;
+}
+
+export function createDefaultWorldSettings(): WorldSettings {
+  return {
+    background: {
+      mode: "solid",
+      colorHex: "#2f3947"
+    },
+    ambientLight: {
+      colorHex: "#f7f1e8",
+      intensity: 1
+    },
+    sunLight: {
+      colorHex: "#fff1d5",
+      intensity: 1.75,
+      direction: DEFAULT_SUN_DIRECTION
+    }
+  };
+}
+
+export function createEmptySceneDocument(overrides: Partial<Pick<SceneDocument, "name" | "world">> = {}): SceneDocument {
+  return {
+    version: SCENE_DOCUMENT_VERSION,
+    name: overrides.name ?? "Untitled Scene",
+    world: overrides.world ?? createDefaultWorldSettings(),
+    materials: {},
+    textures: {},
+    assets: {},
+    brushes: {},
+    modelInstances: {},
+    entities: {},
+    interactionLinks: {}
+  };
+}