@kite3d/engine 0.15.0

package/dist/sceneSerialization.d.ts

@@ -0,0 +1,17 @@
+import { ThreeViewer } from 'threepipe';
+export interface SerializeSceneGltfOptions {
+    scenePath?: string;
+}
+export interface SerializedSceneFile {
+    path: string;
+    bytes: Uint8Array;
+}
+export interface SerializedSceneGltf {
+    document: Record<string, unknown>;
+    gltf: Uint8Array;
+    files: SerializedSceneFile[];
+}
+/** Export a viewer scene as deterministic text glTF plus external resources. */
+export declare function serializeSceneGltf(viewer: Pick<ThreeViewer, 'exportScene'>, options?: SerializeSceneGltfOptions): Promise<SerializedSceneGltf>;
+/** Canonicalize JSON glTF and extract every embedded resource. */
+export declare function serializeSceneGltfDocument(input: unknown, options?: SerializeSceneGltfOptions): Promise<SerializedSceneGltf>;

package/dist/sceneSerialization.js

@@ -0,0 +1,174 @@
+const l = new TextEncoder();
+async function N(e, t = {}) {
+  const n = await e.exportScene({
+    exportExt: "gltf",
+    preserveUUIDs: !0,
+    viewerConfig: !0,
+    embedUrlImages: !1,
+    onlyVisible: !0,
+    jsonSpaces: 2
+  }, !1);
+  if (!n) throw new Error("The scene exporter returned no glTF data");
+  return x(JSON.parse(await n.text()), t);
+}
+async function x(e, t = {}) {
+  if (!a(e) || !a(e.asset))
+    throw new Error("The scene is not a JSON glTF document");
+  const n = U(e);
+  u(n), j(n);
+  const r = T(t.scenePath || "assets/main.scene.gltf"), s = z(r), f = [];
+  E(n, s, P(r), f), await A(n, s, f, 16);
+  const i = y(n);
+  return {
+    document: i,
+    gltf: l.encode(`${JSON.stringify(i, null, 2)}
+`),
+    files: f.sort((d, m) => d.path.localeCompare(m.path))
+  };
+}
+function u(e) {
+  if (Array.isArray(e)) {
+    e.forEach(u);
+    return;
+  }
+  if (a(e)) {
+    if (e.rootSceneModelRoot === !0 && delete e.gltfUUID, a(e.WEBGI_viewer)) {
+      h(e.WEBGI_viewer);
+      const t = e.WEBGI_viewer.scene, n = a(t) ? t.defaultCamera : void 0, r = a(n) ? n.object : void 0;
+      a(r) && delete r.uuid;
+    }
+    Object.values(e).forEach(u);
+  }
+}
+function j(e) {
+  const t = /* @__PURE__ */ new Map();
+  p(e, (n, r) => {
+    t.set(n, (t.get(n) || 0) + 1), typeof r == "string" && t.set(r, (t.get(r) || 0) + 1);
+  }), p(e, (n, r, s) => {
+    n === "uuid" && typeof r == "string" && t.get(r) === 1 && delete s[n];
+  });
+}
+function p(e, t) {
+  if (Array.isArray(e)) {
+    e.forEach((n) => p(n, t));
+    return;
+  }
+  if (a(e))
+    for (const [n, r] of Object.entries(e))
+      t(n, r, e), p(r, t);
+}
+function h(e) {
+  if (Array.isArray(e)) {
+    e.forEach(h);
+    return;
+  }
+  a(e) && (e.isEuler === !0 && (typeof e.order != "string" && (e.order = "XYZ"), typeof e.x != "number" && (e.x = 0), typeof e.y != "number" && (e.y = 0), typeof e.z != "number" && (e.z = 0)), e.autoAspect === !0 && (delete e.aspect, a(e.object) && delete e.object.aspect), Object.values(e).forEach(h));
+}
+function E(e, t, n, r) {
+  const s = e.buffers;
+  if (!(s != null && s.length)) return;
+  const f = s.map((o) => {
+    var c;
+    return (c = o.uri) != null && c.startsWith("data:") ? w(o.uri).bytes : void 0;
+  });
+  if (f.every((o) => o === void 0)) return;
+  if (f.some((o, c) => {
+    var b;
+    return o === void 0 && ((b = s[c]) == null ? void 0 : b.uri);
+  }))
+    throw new Error("A scene cannot combine embedded and external buffers during serialization");
+  let i = 0;
+  const d = f.map((o) => {
+    const c = J(i);
+    return i = c + ((o == null ? void 0 : o.byteLength) || 0), c;
+  }), m = new Uint8Array(i);
+  f.forEach((o, c) => {
+    o && m.set(o, d[c]);
+  });
+  for (const o of e.bufferViews || []) {
+    const c = d[o.buffer];
+    if (c === void 0) throw new Error(`Invalid glTF buffer index: ${o.buffer}`);
+    o.byteOffset = (o.byteOffset || 0) + c, o.buffer = 0;
+  }
+  const g = `${n}.bin`;
+  e.buffers = [{ byteLength: m.byteLength, uri: g }], r.push({ path: $(t, g), bytes: m });
+}
+async function A(e, t, n, r) {
+  var f;
+  const s = /* @__PURE__ */ new Map();
+  for (const i of e.images || []) {
+    if (!((f = i.uri) != null && f.startsWith("data:"))) continue;
+    const d = w(i.uri), m = d.mimeType || i.mimeType || "application/octet-stream", o = `assets/textures/${(await I(d.bytes)).slice(0, r)}.${S(m)}`;
+    s.set(o, d.bytes), i.uri = C(t, o), i.mimeType = m;
+  }
+  for (const [i, d] of s) n.push({ path: i, bytes: d });
+}
+function w(e) {
+  const t = /^data:([^;,]*)(;base64)?,(.*)$/s.exec(e);
+  if (!t) throw new Error("Invalid data URL in glTF");
+  return {
+    bytes: t[2] ? O(t[3]) : l.encode(decodeURIComponent(t[3])),
+    mimeType: t[1] || void 0
+  };
+}
+function O(e) {
+  const t = atob(e);
+  return Uint8Array.from(t, (n) => n.charCodeAt(0));
+}
+async function I(e) {
+  const t = await crypto.subtle.digest("SHA-256", e);
+  return Array.from(new Uint8Array(t), (n) => n.toString(16).padStart(2, "0")).join("");
+}
+function S(e) {
+  var r;
+  const t = e.toLowerCase().split(";", 1)[0];
+  return {
+    "image/avif": "avif",
+    "image/gif": "gif",
+    "image/jpeg": "jpg",
+    "image/ktx2": "ktx2",
+    "image/png": "png",
+    "image/svg+xml": "svg",
+    "image/webp": "webp"
+  }[t] || ((r = t.split("/")[1]) == null ? void 0 : r.replace(/[^a-z0-9.+-]/g, "")) || "bin";
+}
+function y(e) {
+  return Array.isArray(e) ? e.map(y) : a(e) ? Object.fromEntries(Object.keys(e).sort().map((t) => [t, y(e[t])])) : e;
+}
+function U(e) {
+  return JSON.parse(JSON.stringify(e));
+}
+function a(e) {
+  return !!e && typeof e == "object" && !Array.isArray(e);
+}
+function T(e) {
+  const t = e.replace(/\\/g, "/").replace(/^\.\//, "");
+  if (!t || t.startsWith("/") || t.split("/").includes(".."))
+    throw new Error(`Invalid project path: ${e}`);
+  return t;
+}
+function z(e) {
+  const t = e.lastIndexOf("/");
+  return t < 0 ? "" : e.slice(0, t);
+}
+function P(e) {
+  const t = e.slice(e.lastIndexOf("/") + 1), n = t.lastIndexOf(".");
+  return n < 0 ? t : t.slice(0, n);
+}
+function $(e, t) {
+  return e ? `${e}/${t}` : t;
+}
+function C(e, t) {
+  const n = e ? e.split("/") : [], r = t.split("/");
+  for (; n.length && r.length && n[0] === r[0]; )
+    n.shift(), r.shift();
+  return [...n.map(() => ".."), ...r].join("/") || ".";
+}
+function J(e) {
+  return e + 3 & -4;
+}
+export {
+  N as serializeSceneGltf,
+  x as serializeSceneGltfDocument
+};
+//# sourceMappingURL=sceneSerialization.js.map

package/dist/sceneSerialization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sceneSerialization.js","sources":["../src/sceneSerialization.ts"],"sourcesContent":["import type {ThreeViewer} from 'threepipe'\n\nexport interface SerializeSceneGltfOptions {\n    scenePath?: string\n}\n\nexport interface SerializedSceneFile {\n    path: string\n    bytes: Uint8Array\n}\n\nexport interface SerializedSceneGltf {\n    document: Record<string, unknown>\n    gltf: Uint8Array\n    files: SerializedSceneFile[]\n}\n\ninterface GltfBuffer {\n    byteLength?: number\n    uri?: string\n    [key: string]: unknown\n}\n\ninterface GltfBufferView {\n    buffer: number\n    byteOffset?: number\n    [key: string]: unknown\n}\n\ninterface GltfImage {\n    uri?: string\n    mimeType?: string\n    [key: string]: unknown\n}\n\ninterface GltfDocument extends Record<string, unknown> {\n    buffers?: GltfBuffer[]\n    bufferViews?: GltfBufferView[]\n    images?: GltfImage[]\n}\n\nconst encoder = new TextEncoder()\n\n/** Export a viewer scene as deterministic text glTF plus external resources. */\nexport async function serializeSceneGltf(\n    viewer: Pick<ThreeViewer, 'exportScene'>,\n    options: SerializeSceneGltfOptions = {},\n): Promise<SerializedSceneGltf> {\n    const blob = await viewer.exportScene({\n        exportExt: 'gltf',\n        preserveUUIDs: true,\n        viewerConfig: true,\n        embedUrlImages: false,\n        onlyVisible: true,\n        jsonSpaces: 2,\n    }, false)\n    if (!blob) throw new Error('The scene exporter returned no glTF data')\n    return serializeSceneGltfDocument(JSON.parse(await blob.text()), options)\n}\n\n/** Canonicalize JSON glTF and extract every embedded resource. */\nexport async function serializeSceneGltfDocument(\n    input: unknown,\n    options: SerializeSceneGltfOptions = {},\n): Promise<SerializedSceneGltf> {\n    if (!isRecord(input) || !isRecord(input.asset)) {\n        throw new Error('The scene is not a JSON glTF document')\n    }\n    const document = cloneJson(input) as GltfDocument\n    removeVolatileViewerIds(document)\n    removeUnreferencedUuids(document)\n    const scenePath = normalizeProjectPath(options.scenePath || 'assets/main.scene.gltf')\n    const sceneDirectory = directoryName(scenePath)\n    const files: SerializedSceneFile[] = []\n\n    extractBuffers(document, sceneDirectory, fileStem(scenePath), files)\n    await extractImages(document, sceneDirectory, files, 16)\n\n    const sorted = sortObjectKeys(document) as GltfDocument\n    return {\n        document: sorted,\n        gltf: encoder.encode(`${JSON.stringify(sorted, null, 2)}\\n`),\n        files: files.sort((left, right) => left.path.localeCompare(right.path)),\n    }\n}\n\nfunction removeVolatileViewerIds(value: unknown): void {\n    if (Array.isArray(value)) {\n        value.forEach(removeVolatileViewerIds)\n        return\n    }\n    if (!isRecord(value)) return\n    if (value.rootSceneModelRoot === true) delete value.gltfUUID\n    if (isRecord(value.WEBGI_viewer)) {\n        canonicalizeViewerConfig(value.WEBGI_viewer)\n        const scene = value.WEBGI_viewer.scene\n        const camera = isRecord(scene) ? scene.defaultCamera : undefined\n        const object = isRecord(camera) ? camera.object : undefined\n        if (isRecord(object)) delete object.uuid\n    }\n    Object.values(value).forEach(removeVolatileViewerIds)\n}\n\nfunction removeUnreferencedUuids(document: GltfDocument): void {\n    const uses = new Map<string, number>()\n    visitJson(document, (key, value) => {\n        uses.set(key, (uses.get(key) || 0) + 1)\n        if (typeof value === 'string') uses.set(value, (uses.get(value) || 0) + 1)\n    })\n    visitJson(document, (key, value, owner) => {\n        if (key === 'uuid' && typeof value === 'string' && uses.get(value) === 1) delete owner[key]\n    })\n}\n\nfunction visitJson(\n    value: unknown,\n    visit: (key: string, value: unknown, owner: Record<string, unknown>) => void,\n): void {\n    if (Array.isArray(value)) {\n        value.forEach((child) => visitJson(child, visit))\n        return\n    }\n    if (!isRecord(value)) return\n    for (const [key, child] of Object.entries(value)) {\n        visit(key, child, value)\n        visitJson(child, visit)\n    }\n}\n\nfunction canonicalizeViewerConfig(value: unknown): void {\n    if (Array.isArray(value)) {\n        value.forEach(canonicalizeViewerConfig)\n        return\n    }\n    if (!isRecord(value)) return\n    if (value.isEuler === true) {\n        if (typeof value.order !== 'string') value.order = 'XYZ'\n        if (typeof value.x !== 'number') value.x = 0\n        if (typeof value.y !== 'number') value.y = 0\n        if (typeof value.z !== 'number') value.z = 0\n    }\n    if (value.autoAspect === true) {\n        delete value.aspect\n        if (isRecord(value.object)) delete value.object.aspect\n    }\n    Object.values(value).forEach(canonicalizeViewerConfig)\n}\n\nfunction extractBuffers(\n    document: GltfDocument,\n    sceneDirectory: string,\n    baseName: string,\n    files: SerializedSceneFile[],\n): void {\n    const buffers = document.buffers\n    if (!buffers?.length) return\n\n    const embedded = buffers.map((buffer) => buffer.uri?.startsWith('data:') ? decodeDataUrl(buffer.uri).bytes : undefined)\n    if (embedded.every((value) => value === undefined)) return\n    if (embedded.some((value, index) => value === undefined && buffers[index]?.uri)) {\n        throw new Error('A scene cannot combine embedded and external buffers during serialization')\n    }\n\n    let byteLength = 0\n    const offsets = embedded.map((bytes) => {\n        const offset = align4(byteLength)\n        byteLength = offset + (bytes?.byteLength || 0)\n        return offset\n    })\n    const combined = new Uint8Array(byteLength)\n    embedded.forEach((bytes, index) => {\n        if (bytes) combined.set(bytes, offsets[index])\n    })\n\n    for (const view of document.bufferViews || []) {\n        const offset = offsets[view.buffer]\n        if (offset === undefined) throw new Error(`Invalid glTF buffer index: ${view.buffer}`)\n        view.byteOffset = (view.byteOffset || 0) + offset\n        view.buffer = 0\n    }\n\n    const binName = `${baseName}.bin`\n    document.buffers = [{byteLength: combined.byteLength, uri: binName}]\n    files.push({path: joinProjectPath(sceneDirectory, binName), bytes: combined})\n}\n\nasync function extractImages(\n    document: GltfDocument,\n    sceneDirectory: string,\n    files: SerializedSceneFile[],\n    hashLength: number,\n): Promise<void> {\n    const byPath = new Map<string, Uint8Array>()\n    for (const image of document.images || []) {\n        if (!image.uri?.startsWith('data:')) continue\n        const decoded = decodeDataUrl(image.uri)\n        const mimeType = decoded.mimeType || image.mimeType || 'application/octet-stream'\n        const hash = await sha256(decoded.bytes)\n        const path = `assets/textures/${hash.slice(0, hashLength)}.${imageExtension(mimeType)}`\n        byPath.set(path, decoded.bytes)\n        image.uri = relativeProjectPath(sceneDirectory, path)\n        image.mimeType = mimeType\n    }\n    for (const [path, bytes] of byPath) files.push({path, bytes})\n}\n\nfunction decodeDataUrl(uri: string): {bytes: Uint8Array, mimeType?: string} {\n    const match = /^data:([^;,]*)(;base64)?,(.*)$/s.exec(uri)\n    if (!match) throw new Error('Invalid data URL in glTF')\n    return {\n        bytes: match[2] ? decodeBase64(match[3]) : encoder.encode(decodeURIComponent(match[3])),\n        mimeType: match[1] || undefined,\n    }\n}\n\nfunction decodeBase64(value: string): Uint8Array {\n    const decoded = atob(value)\n    return Uint8Array.from(decoded, (character) => character.charCodeAt(0))\n}\n\nasync function sha256(bytes: Uint8Array): Promise<string> {\n    const digest = await crypto.subtle.digest('SHA-256', bytes as BufferSource)\n    return Array.from(new Uint8Array(digest), (value) => value.toString(16).padStart(2, '0')).join('')\n}\n\nfunction imageExtension(mimeType: string): string {\n    const normalized = mimeType.toLowerCase().split(';', 1)[0]\n    const extensions: Record<string, string> = {\n        'image/avif': 'avif',\n        'image/gif': 'gif',\n        'image/jpeg': 'jpg',\n        'image/ktx2': 'ktx2',\n        'image/png': 'png',\n        'image/svg+xml': 'svg',\n        'image/webp': 'webp',\n    }\n    return extensions[normalized] || normalized.split('/')[1]?.replace(/[^a-z0-9.+-]/g, '') || 'bin'\n}\n\nfunction sortObjectKeys(value: unknown): unknown {\n    if (Array.isArray(value)) return value.map(sortObjectKeys)\n    if (!isRecord(value)) return value\n    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortObjectKeys(value[key])]))\n}\n\nfunction cloneJson<T>(value: T): T {\n    return JSON.parse(JSON.stringify(value)) as T\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n    return Boolean(value) && typeof value === 'object' && !Array.isArray(value)\n}\n\nfunction normalizeProjectPath(path: string): string {\n    const normalized = path.replace(/\\\\/g, '/').replace(/^\\.\\//, '')\n    if (!normalized || normalized.startsWith('/') || normalized.split('/').includes('..')) {\n        throw new Error(`Invalid project path: ${path}`)\n    }\n    return normalized\n}\n\nfunction directoryName(path: string): string {\n    const end = path.lastIndexOf('/')\n    return end < 0 ? '' : path.slice(0, end)\n}\n\nfunction fileStem(path: string): string {\n    const name = path.slice(path.lastIndexOf('/') + 1)\n    const end = name.lastIndexOf('.')\n    return end < 0 ? name : name.slice(0, end)\n}\n\nfunction joinProjectPath(directory: string, name: string): string {\n    return directory ? `${directory}/${name}` : name\n}\n\nfunction relativeProjectPath(fromDirectory: string, target: string): string {\n    const from = fromDirectory ? fromDirectory.split('/') : []\n    const to = target.split('/')\n    while (from.length && to.length && from[0] === to[0]) {\n        from.shift()\n        to.shift()\n    }\n    return [...from.map(() => '..'), ...to].join('/') || '.'\n}\n\nfunction align4(value: number): number {\n    return (value + 3) & ~3\n}\n"],"names":["encoder","serializeSceneGltf","viewer","options","blob","serializeSceneGltfDocument","input","isRecord","document","cloneJson","removeVolatileViewerIds","removeUnreferencedUuids","scenePath","normalizeProjectPath","sceneDirectory","directoryName","files","extractBuffers","fileStem","extractImages","sorted","sortObjectKeys","left","right","value","canonicalizeViewerConfig","scene","camera","object","uses","visitJson","key","owner","visit","child","baseName","buffers","embedded","buffer","_a","decodeDataUrl","index","byteLength","offsets","bytes","offset","align4","combined","view","binName","joinProjectPath","hashLength","byPath","image","decoded","mimeType","path","sha256","imageExtension","relativeProjectPath","uri","match","decodeBase64","character","digest","normalized","end","name","directory","fromDirectory","target","from","to"],"mappings":"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"}

package/dist/scripts.d.ts

@@ -0,0 +1,17 @@
+import { Class, IViewerPlugin, ThreeViewer, TObject3DComponent } from 'threepipe';
+export type ScriptModule = Record<string, unknown>;
+export interface WalkedScriptExports {
+    plugins: Array<{
+        name: string;
+        value: Class<IViewerPlugin>;
+    }>;
+    components: Array<{
+        name: string;
+        value: TObject3DComponent;
+    }>;
+}
+export declare function walkScriptExports(module: ScriptModule): WalkedScriptExports;
+/** Register every plugin and Object3D component exported by project modules. */
+export declare function registerScripts(viewer: ThreeViewer, modules: Iterable<ScriptModule>): Promise<WalkedScriptExports>;
+export declare function isPluginType(value: unknown): value is Class<IViewerPlugin>;
+export declare function isComponentType(value: unknown): value is TObject3DComponent;

package/dist/version.js

@@ -0,0 +1,7 @@
+const n = "0.15.0", e = {
+  version: n
+}, o = e.version;
+export {
+  o as RUNTIME_VERSION
+};
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sources":["../src/runtime/version.ts"],"sourcesContent":["import enginePackage from '../../package.json'\n\nexport const RUNTIME_VERSION = enginePackage.version\n"],"names":["RUNTIME_VERSION","enginePackage"],"mappings":";;GAEaA,IAAkBC,EAAc;"}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@kite3d/engine",
+  "version": "0.15.0",
+  "description": "The open Kite3D game runtime, project format, scripting helpers, and game plugins.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./fileTypes": {
+      "types": "./dist/fileTypes.d.ts",
+      "import": "./dist/fileTypes.js"
+    },
+    "./paths": {
+      "types": "./dist/paths.d.ts",
+      "import": "./dist/paths.js"
+    },
+    "./sceneSerialization": {
+      "types": "./dist/sceneSerialization.d.ts",
+      "import": "./dist/sceneSerialization.js"
+    },
+    "./authoring": {
+      "types": "./dist/authoring.d.ts",
+      "import": "./dist/authoring.js"
+    },
+    "./authoringValidation": {
+      "types": "./dist/authoringValidation.d.ts",
+      "import": "./dist/authoringValidation.js"
+    },
+    "./version": {
+      "types": "./dist/runtime/version.d.ts",
+      "import": "./dist/version.js"
+    },
+    "./projectFormat": {
+      "types": "./dist/runtime/projectFormat.d.ts",
+      "import": "./dist/projectFormat.js"
+    },
+    "./migrations": {
+      "types": "./dist/runtime/migrations.d.ts",
+      "import": "./dist/migrations.js"
+    },
+    "./importMap": {
+      "types": "./dist/importMap.d.ts",
+      "import": "./dist/importMap.js"
+    },
+    "./runtime.js": "./dist/runtime.js",
+    "./package.json": "./package.json",
+    "./src/*": "./src/*"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build && vite build --config vite.runtime.config.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext ts --report-unused-disable-directives --max-warnings 0",
+    "test": "vitest run test/unit",
+    "test:gates": "npm run build && playwright test persistence-gate.spec.ts startup-failures.spec.ts release-gates.spec.ts",
+    "test:runtime": "npm run build && vitest run test/unit && playwright test"
+  },
+  "dependencies": {
+    "cannon-es": "^0.20.0",
+    "jsonc-parser": "^3.3.1",
+    "meshoptimizer": "^0.20.0",
+    "threepipe": "0.5.1",
+    "ts-browser-helpers": "0.19.4",
+    "uiconfig.js": "^0.3.1"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.57.0",
+    "@types/node": "^22.1.0",
+    "@typescript-eslint/eslint-plugin": "^6.14.0",
+    "@typescript-eslint/parser": "^6.14.0",
+    "eslint": "^8.55.0",
+    "typescript": "^5.7.2",
+    "vite": "^6.3.5",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^3.2.4"
+  }
+}

package/src/authoring.ts

@@ -0,0 +1,293 @@
+import type {IObject3D} from 'threepipe'
+
+export const KITE3D_AUTHORING_METADATA_KEY = 'kite3dAuthoring'
+export const KITE3D_RUNTIME_METADATA_KEY = 'kite3dRuntime'
+
+export type AuthoringRole = 'direct' | 'template' | 'generator'
+
+export interface AuthoringMetadata {
+    role: AuthoringRole
+    id: string
+    sourceId?: string
+    allowCameraInside?: boolean
+}
+
+export interface RuntimeObjectMetadata {
+    ownerId: string
+    kind: 'clone' | 'effect'
+    sourceId: string
+    overrides?: RuntimeMutableProperty[]
+}
+
+export type RuntimeMutableProperty = 'position' | 'rotation' | 'scale' | 'visible' | 'material'
+
+export interface RuntimeCloneOptions {
+    name?: string
+    visible?: boolean
+    position?: [number, number, number]
+    rotation?: [number, number, number]
+    scale?: [number, number, number]
+    runtimeMutable?: RuntimeMutableProperty[]
+}
+
+export interface RuntimeScene extends IObject3D {
+    modelRoot: IObject3D
+}
+
+interface TrackedRuntimeObject {
+    object: IObject3D
+    owner: IObject3D
+    scene?: RuntimeScene
+}
+
+const authoringRoles = new Set<AuthoringRole>(['direct', 'template', 'generator'])
+const trackedRuntimeObjects = new Map<IObject3D, TrackedRuntimeObject>()
+
+/** Store a validated, serializable authored identity on an object. */
+export function setAuthoringMetadata(object: IObject3D, metadata: AuthoringMetadata): AuthoringMetadata {
+    const value = normalizeAuthoringMetadata(metadata)
+    object.userData[KITE3D_AUTHORING_METADATA_KEY] = value
+    object.setDirty?.({source: 'Kite3D authoring', change: `userData.${KITE3D_AUTHORING_METADATA_KEY}`})
+    return value
+}
+
+/** Read authoring metadata without trusting arbitrary userData. */
+export function getAuthoringMetadata(object: IObject3D): AuthoringMetadata | undefined {
+    const value = object.userData?.[KITE3D_AUTHORING_METADATA_KEY]
+    if (!isRecord(value) || !authoringRoles.has(value.role as AuthoringRole)
+        || typeof value.id !== 'string' || !value.id.trim()
+        || (value.sourceId !== undefined && (typeof value.sourceId !== 'string' || !value.sourceId.trim()))
+        || (value.allowCameraInside !== undefined && typeof value.allowCameraInside !== 'boolean')) return undefined
+    return value as unknown as AuthoringMetadata
+}
+
+export function getRuntimeObjectMetadata(object: IObject3D): RuntimeObjectMetadata | undefined {
+    const value = object.userData?.[KITE3D_RUNTIME_METADATA_KEY]
+    if (!isRecord(value) || typeof value.ownerId !== 'string' || !value.ownerId
+        || !['clone', 'effect'].includes(String(value.kind))
+        || typeof value.sourceId !== 'string' || !value.sourceId) return undefined
+    return value as unknown as RuntimeObjectMetadata
+}
+
+export function isRuntimeObject(object: IObject3D): boolean {
+    return getRuntimeObjectMetadata(object) !== undefined
+}
+
+/** Return the live objects tracked against one viewer scene. */
+export function getTrackedRuntimeObjects(scene: IObject3D): readonly IObject3D[] {
+    return [...trackedRuntimeObjects.values()]
+        .filter((record) => record.scene === scene)
+        .map(({object}) => object)
+}
+
+/**
+ * Owns Play-only roots and clones. A single owner should be created in start()
+ * and cleaned in stop(); cleanup is idempotent.
+ */
+export class RuntimeObjectOwner {
+    private readonly objects = new Set<IObject3D>()
+    private readonly protectedResources = new Set<object>()
+    private runtimeParent?: IObject3D
+    private nextObject = 0
+
+    constructor(readonly ownerId: string) {
+        if (!ownerId?.trim()) throw new Error('RuntimeObjectOwner requires a stable owner id')
+    }
+
+    attachRuntimeRoot<T extends IObject3D>(root: T, scene: RuntimeScene, authoredOwner: IObject3D): T {
+        if ((root as IObject3D) === (scene as IObject3D) || root === scene.modelRoot
+            || root === authoredOwner || isDescendantOf(authoredOwner, root)) {
+            throw new Error('A runtime root cannot be its authored owner or an ancestor of that owner')
+        }
+        if (!isDescendantOf(authoredOwner, scene.modelRoot)) {
+            throw new Error('A runtime root requires an authored owner beneath modelRoot')
+        }
+        this.track(root, authoredOwner, 'effect', scene)
+        scene.add(root)
+        this.runtimeParent = root
+        return root
+    }
+
+    trackEffect<T extends IObject3D>(root: T, owner: IObject3D): T {
+        if (root === owner || isDescendantOf(owner, root) || isRuntimeObject(owner)) {
+            throw new Error('An effect root requires a persistent authored owner outside that root')
+        }
+        const scene = findTrackedScene(root) || findRuntimeScene(owner)
+        if (scene && isDescendantOf(root, scene.modelRoot)) {
+            throw new Error('Runtime effects must live outside modelRoot')
+        }
+        this.track(root, owner, 'effect', scene)
+        return root
+    }
+
+    cloneFrom<T extends IObject3D>(source: T, parent: IObject3D | undefined = this.runtimeParent, options: RuntimeCloneOptions = {}): T {
+        const sourceMetadata = getAuthoringMetadata(source)
+        if (!sourceMetadata || sourceMetadata.sourceId) {
+            throw new Error('Runtime clones require a direct, template, or generator source with a stable authored id')
+        }
+        if (!parent) throw new Error('Runtime clones require a parent or an attached runtime root')
+        const scene = findTrackedScene(parent) || findRuntimeScene(source) || findRuntimeScene(parent)
+        if (scene && isDescendantOf(parent, scene.modelRoot)) {
+            throw new Error('Runtime clones must live outside modelRoot')
+        }
+
+        collectResources(source, this.protectedResources)
+        const clone = source.clone(true) as T
+        clone.traverse((child) => {
+            if (child !== clone) {
+                delete child.userData?.[KITE3D_AUTHORING_METADATA_KEY]
+                delete child.userData?.[KITE3D_RUNTIME_METADATA_KEY]
+            }
+            cloneMaterials(child)
+        })
+        clone.name = options.name || `${source.name || sourceMetadata.id} (Runtime)`
+        clone.visible = options.visible ?? true
+        if (options.position) clone.position.set(...options.position)
+        if (options.rotation) clone.rotation.set(...options.rotation)
+        if (options.scale) clone.scale.set(...options.scale)
+
+        const overrides = new Set<RuntimeMutableProperty>(options.runtimeMutable || ['position', 'rotation'])
+        if (options.position) overrides.add('position')
+        if (options.rotation) overrides.add('rotation')
+        if (options.scale) overrides.add('scale')
+        if (options.visible !== undefined || clone.visible !== source.visible) overrides.add('visible')
+        this.markRuntimeObject(clone, sourceMetadata, 'clone', [...overrides])
+        parent.add(clone)
+        this.objects.add(clone)
+        trackedRuntimeObjects.set(clone, {object: clone, owner: source, scene})
+        return clone
+    }
+
+    cleanup(): void {
+        const disposed = new Set<object>()
+        for (const object of this.objects) {
+            object.removeFromParent()
+            disposeObjectResources(object, this.protectedResources, disposed)
+            trackedRuntimeObjects.delete(object)
+        }
+        this.objects.clear()
+        this.protectedResources.clear()
+        this.runtimeParent = undefined
+    }
+
+    private track<T extends IObject3D>(
+        object: T,
+        owner: IObject3D,
+        kind: RuntimeObjectMetadata['kind'],
+        scene?: RuntimeScene,
+    ): void {
+        const ownerMetadata = getAuthoringMetadata(owner)
+        const sourceId = ownerMetadata?.id || owner.uuid
+        collectResources(owner, this.protectedResources)
+        this.markRuntimeObject(object, ownerMetadata || {role: 'direct', id: sourceId}, kind)
+        this.objects.add(object)
+        trackedRuntimeObjects.set(object, {object, owner, scene})
+    }
+
+    private markRuntimeObject(
+        object: IObject3D,
+        source: AuthoringMetadata,
+        kind: RuntimeObjectMetadata['kind'],
+        overrides?: RuntimeMutableProperty[],
+    ): void {
+        const sourceId = source.id
+        object.userData[KITE3D_AUTHORING_METADATA_KEY] = {
+            role: source.role,
+            id: `${this.ownerId}:${++this.nextObject}`,
+            sourceId,
+        } satisfies AuthoringMetadata
+        object.userData[KITE3D_RUNTIME_METADATA_KEY] = {
+            ownerId: this.ownerId,
+            kind,
+            sourceId,
+            ...(overrides?.length ? {overrides} : {}),
+        } satisfies RuntimeObjectMetadata
+    }
+}
+
+function normalizeAuthoringMetadata(metadata: AuthoringMetadata): AuthoringMetadata {
+    if (!metadata || !authoringRoles.has(metadata.role) || typeof metadata.id !== 'string' || !metadata.id.trim()) {
+        throw new Error('Kite3D authoring metadata requires a supported role and stable id')
+    }
+    if (metadata.sourceId !== undefined && (typeof metadata.sourceId !== 'string' || !metadata.sourceId.trim())) {
+        throw new Error('Kite3D authoring sourceId must be a non-empty string')
+    }
+    if (metadata.allowCameraInside !== undefined && typeof metadata.allowCameraInside !== 'boolean') {
+        throw new Error('Kite3D allowCameraInside must be a boolean')
+    }
+    return {
+        role: metadata.role,
+        id: metadata.id.trim(),
+        ...(metadata.sourceId ? {sourceId: metadata.sourceId.trim()} : {}),
+        ...(metadata.allowCameraInside !== undefined ? {allowCameraInside: metadata.allowCameraInside} : {}),
+    }
+}
+
+function cloneMaterials(object: IObject3D): void {
+    const renderable = object as IObject3D & {material?: {clone?: () => unknown} | Array<{clone?: () => unknown}>}
+    if (Array.isArray(renderable.material)) {
+        renderable.material = renderable.material.map((material) => material?.clone?.() || material) as typeof renderable.material
+    } else if (renderable.material) {
+        renderable.material = (renderable.material.clone?.() || renderable.material) as typeof renderable.material
+    }
+}
+
+function findTrackedScene(object: IObject3D): RuntimeScene | undefined {
+    for (let current: IObject3D | null = object; current; current = current.parent as IObject3D | null) {
+        const record = trackedRuntimeObjects.get(current)
+        if (record?.scene) return record.scene
+    }
+    return undefined
+}
+
+function findRuntimeScene(object: IObject3D): RuntimeScene | undefined {
+    let current: IObject3D | null = object
+    while (current?.parent) current = current.parent as IObject3D
+    return current && 'modelRoot' in current ? current as RuntimeScene : undefined
+}
+
+function isDescendantOf(object: IObject3D, ancestor: IObject3D): boolean {
+    for (let current: IObject3D | null = object; current; current = current.parent as IObject3D | null) {
+        if (current === ancestor) return true
+    }
+    return false
+}
+
+function collectResources(object: IObject3D, target: Set<object>): void {
+    object.traverse((child) => {
+        const resourceOwner = child as IObject3D & {geometry?: object, material?: object | object[]}
+        if (resourceOwner.geometry) target.add(resourceOwner.geometry)
+        const materials = Array.isArray(resourceOwner.material) ? resourceOwner.material : [resourceOwner.material]
+        for (const material of materials) {
+            if (!material) continue
+            target.add(material)
+            for (const value of Object.values(material)) {
+                if (isRecord(value) && value.isTexture === true) target.add(value)
+            }
+        }
+    })
+}
+
+function disposeObjectResources(object: IObject3D, protectedResources: Set<object>, disposed: Set<object>): void {
+    const dispose = (resource: unknown) => {
+        if (!isRecord(resource) || protectedResources.has(resource) || disposed.has(resource)) return
+        disposed.add(resource)
+        if (typeof resource.dispose === 'function') resource.dispose()
+    }
+    object.traverse((child) => {
+        const resourceOwner = child as IObject3D & {geometry?: object, material?: object | object[]}
+        dispose(resourceOwner.geometry)
+        const materials = Array.isArray(resourceOwner.material) ? resourceOwner.material : [resourceOwner.material]
+        for (const material of materials) {
+            if (!material) continue
+            for (const value of Object.values(material)) {
+                if (isRecord(value) && value.isTexture === true) dispose(value)
+            }
+            dispose(material)
+        }
+    })
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}