@kite3d/engine 0.15.0

package/dist/authoring.d.ts

@@ -0,0 +1,54 @@
+import { IObject3D } from 'threepipe';
+export declare const KITE3D_AUTHORING_METADATA_KEY = "kite3dAuthoring";
+export declare 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;
+}
+/** Store a validated, serializable authored identity on an object. */
+export declare function setAuthoringMetadata(object: IObject3D, metadata: AuthoringMetadata): AuthoringMetadata;
+/** Read authoring metadata without trusting arbitrary userData. */
+export declare function getAuthoringMetadata(object: IObject3D): AuthoringMetadata | undefined;
+export declare function getRuntimeObjectMetadata(object: IObject3D): RuntimeObjectMetadata | undefined;
+export declare function isRuntimeObject(object: IObject3D): boolean;
+/** Return the live objects tracked against one viewer scene. */
+export declare function getTrackedRuntimeObjects(scene: IObject3D): readonly IObject3D[];
+/**
+ * Owns Play-only roots and clones. A single owner should be created in start()
+ * and cleaned in stop(); cleanup is idempotent.
+ */
+export declare class RuntimeObjectOwner {
+    readonly ownerId: string;
+    private readonly objects;
+    private readonly protectedResources;
+    private runtimeParent?;
+    private nextObject;
+    constructor(ownerId: string);
+    attachRuntimeRoot<T extends IObject3D>(root: T, scene: RuntimeScene, authoredOwner: IObject3D): T;
+    trackEffect<T extends IObject3D>(root: T, owner: IObject3D): T;
+    cloneFrom<T extends IObject3D>(source: T, parent?: IObject3D | undefined, options?: RuntimeCloneOptions): T;
+    cleanup(): void;
+    private track;
+    private markRuntimeObject;
+}

package/dist/authoring.js

@@ -0,0 +1,165 @@
+const l = "kite3dAuthoring", h = "kite3dRuntime", g = /* @__PURE__ */ new Set(["direct", "template", "generator"]), d = /* @__PURE__ */ new Map();
+function O(r, e) {
+  var i;
+  const t = A(e);
+  return r.userData[l] = t, (i = r.setDirty) == null || i.call(r, { source: "Kite3D authoring", change: `userData.${l}` }), t;
+}
+function b(r) {
+  var t;
+  const e = (t = r.userData) == null ? void 0 : t[l];
+  if (!(!f(e) || !g.has(e.role) || typeof e.id != "string" || !e.id.trim() || e.sourceId !== void 0 && (typeof e.sourceId != "string" || !e.sourceId.trim()) || e.allowCameraInside !== void 0 && typeof e.allowCameraInside != "boolean"))
+    return e;
+}
+function p(r) {
+  var t;
+  const e = (t = r.userData) == null ? void 0 : t[h];
+  if (!(!f(e) || typeof e.ownerId != "string" || !e.ownerId || !["clone", "effect"].includes(String(e.kind)) || typeof e.sourceId != "string" || !e.sourceId))
+    return e;
+}
+function y(r) {
+  return p(r) !== void 0;
+}
+function j(r) {
+  return [...d.values()].filter((e) => e.scene === r).map(({ object: e }) => e);
+}
+class k {
+  constructor(e) {
+    if (this.ownerId = e, this.objects = /* @__PURE__ */ new Set(), this.protectedResources = /* @__PURE__ */ new Set(), this.nextObject = 0, !(e != null && e.trim())) throw new Error("RuntimeObjectOwner requires a stable owner id");
+  }
+  attachRuntimeRoot(e, t, i) {
+    if (e === t || e === t.modelRoot || e === i || u(i, e))
+      throw new Error("A runtime root cannot be its authored owner or an ancestor of that owner");
+    if (!u(i, t.modelRoot))
+      throw new Error("A runtime root requires an authored owner beneath modelRoot");
+    return this.track(e, i, "effect", t), t.add(e), this.runtimeParent = e, e;
+  }
+  trackEffect(e, t) {
+    if (e === t || u(t, e) || y(t))
+      throw new Error("An effect root requires a persistent authored owner outside that root");
+    const i = I(e) || m(t);
+    if (i && u(e, i.modelRoot))
+      throw new Error("Runtime effects must live outside modelRoot");
+    return this.track(e, t, "effect", i), e;
+  }
+  cloneFrom(e, t = this.runtimeParent, i = {}) {
+    const n = b(e);
+    if (!n || n.sourceId)
+      throw new Error("Runtime clones require a direct, template, or generator source with a stable authored id");
+    if (!t) throw new Error("Runtime clones require a parent or an attached runtime root");
+    const o = I(t) || m(e) || m(t);
+    if (o && u(t, o.modelRoot))
+      throw new Error("Runtime clones must live outside modelRoot");
+    v(e, this.protectedResources);
+    const s = e.clone(!0);
+    s.traverse((c) => {
+      var w, R;
+      c !== s && ((w = c.userData) == null || delete w[l], (R = c.userData) == null || delete R[h]), E(c);
+    }), s.name = i.name || `${e.name || n.id} (Runtime)`, s.visible = i.visible ?? !0, i.position && s.position.set(...i.position), i.rotation && s.rotation.set(...i.rotation), i.scale && s.scale.set(...i.scale);
+    const a = new Set(i.runtimeMutable || ["position", "rotation"]);
+    return i.position && a.add("position"), i.rotation && a.add("rotation"), i.scale && a.add("scale"), (i.visible !== void 0 || s.visible !== e.visible) && a.add("visible"), this.markRuntimeObject(s, n, "clone", [...a]), t.add(s), this.objects.add(s), d.set(s, { object: s, owner: e, scene: o }), s;
+  }
+  cleanup() {
+    const e = /* @__PURE__ */ new Set();
+    for (const t of this.objects)
+      t.removeFromParent(), D(t, this.protectedResources, e), d.delete(t);
+    this.objects.clear(), this.protectedResources.clear(), this.runtimeParent = void 0;
+  }
+  track(e, t, i, n) {
+    const o = b(t), s = (o == null ? void 0 : o.id) || t.uuid;
+    v(t, this.protectedResources), this.markRuntimeObject(e, o || { role: "direct", id: s }, i), this.objects.add(e), d.set(e, { object: e, owner: t, scene: n });
+  }
+  markRuntimeObject(e, t, i, n) {
+    const o = t.id;
+    e.userData[l] = {
+      role: t.role,
+      id: `${this.ownerId}:${++this.nextObject}`,
+      sourceId: o
+    }, e.userData[h] = {
+      ownerId: this.ownerId,
+      kind: i,
+      sourceId: o,
+      ...n != null && n.length ? { overrides: n } : {}
+    };
+  }
+}
+function A(r) {
+  if (!r || !g.has(r.role) || typeof r.id != "string" || !r.id.trim())
+    throw new Error("Kite3D authoring metadata requires a supported role and stable id");
+  if (r.sourceId !== void 0 && (typeof r.sourceId != "string" || !r.sourceId.trim()))
+    throw new Error("Kite3D authoring sourceId must be a non-empty string");
+  if (r.allowCameraInside !== void 0 && typeof r.allowCameraInside != "boolean")
+    throw new Error("Kite3D allowCameraInside must be a boolean");
+  return {
+    role: r.role,
+    id: r.id.trim(),
+    ...r.sourceId ? { sourceId: r.sourceId.trim() } : {},
+    ...r.allowCameraInside !== void 0 ? { allowCameraInside: r.allowCameraInside } : {}
+  };
+}
+function E(r) {
+  var t, i;
+  const e = r;
+  Array.isArray(e.material) ? e.material = e.material.map((n) => {
+    var o;
+    return ((o = n == null ? void 0 : n.clone) == null ? void 0 : o.call(n)) || n;
+  }) : e.material && (e.material = ((i = (t = e.material).clone) == null ? void 0 : i.call(t)) || e.material);
+}
+function I(r) {
+  for (let e = r; e; e = e.parent) {
+    const t = d.get(e);
+    if (t != null && t.scene) return t.scene;
+  }
+}
+function m(r) {
+  let e = r;
+  for (; e != null && e.parent; ) e = e.parent;
+  return e && "modelRoot" in e ? e : void 0;
+}
+function u(r, e) {
+  for (let t = r; t; t = t.parent)
+    if (t === e) return !0;
+  return !1;
+}
+function v(r, e) {
+  r.traverse((t) => {
+    const i = t;
+    i.geometry && e.add(i.geometry);
+    const n = Array.isArray(i.material) ? i.material : [i.material];
+    for (const o of n)
+      if (o) {
+        e.add(o);
+        for (const s of Object.values(o))
+          f(s) && s.isTexture === !0 && e.add(s);
+      }
+  });
+}
+function D(r, e, t) {
+  const i = (n) => {
+    !f(n) || e.has(n) || t.has(n) || (t.add(n), typeof n.dispose == "function" && n.dispose());
+  };
+  r.traverse((n) => {
+    const o = n;
+    i(o.geometry);
+    const s = Array.isArray(o.material) ? o.material : [o.material];
+    for (const a of s)
+      if (a) {
+        for (const c of Object.values(a))
+          f(c) && c.isTexture === !0 && i(c);
+        i(a);
+      }
+  });
+}
+function f(r) {
+  return !!r && typeof r == "object" && !Array.isArray(r);
+}
+export {
+  l as KITE3D_AUTHORING_METADATA_KEY,
+  h as KITE3D_RUNTIME_METADATA_KEY,
+  k as RuntimeObjectOwner,
+  b as getAuthoringMetadata,
+  p as getRuntimeObjectMetadata,
+  j as getTrackedRuntimeObjects,
+  y as isRuntimeObject,
+  O as setAuthoringMetadata
+};
+//# sourceMappingURL=authoring.js.map

package/dist/authoring.js.map

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

package/dist/authoringValidation.d.ts

@@ -0,0 +1,110 @@
+import { IObject3D, ThreeViewer } from 'threepipe';
+export type AuthoringFailureCode = 'NO_VISIBLE_AUTHORED_CONTENT' | 'GENERATOR_PREVIEW_MISSING' | 'RUNTIME_OBJECT_AFTER_STOP' | 'MISSING_AUTHORING_SOURCE' | 'RUNTIME_SOURCE_DRIFT' | 'CAMERA_NOT_USEFUL' | 'CAMERA_CONTAINMENT_UNVERIFIED' | 'PERSISTENCE_DRIFT';
+export interface AuthoringValidationIssue {
+    code: AuthoringFailureCode;
+    severity: 'error' | 'warning';
+    message: string;
+    object?: {
+        uuid: string;
+        name: string;
+    };
+    path?: string;
+    before?: unknown;
+    after?: unknown;
+}
+export interface AuthoringQualityReport {
+    ok: boolean;
+    status: 'pass' | 'fail';
+    summary: string;
+    issues: AuthoringValidationIssue[];
+    checks: {
+        visibleAuthoredContent: boolean;
+        selectableAuthoredContent: boolean;
+        relationshipsValid: boolean;
+        generatorPreviews: boolean;
+        cameraUseful: boolean;
+    };
+    metrics: {
+        authoredObjectCount: number;
+        renderableCount: number;
+        visibleRenderableCount: number;
+        selectableCount: number;
+        generatorCount: number;
+        generatorPreviewCount: number;
+        cameraFramedRenderableCount: number;
+        cameraInsideRenderableCount: number;
+    };
+}
+export interface RuntimeCleanupReport {
+    ok: boolean;
+    status: 'pass' | 'fail';
+    summary: string;
+    issues: AuthoringValidationIssue[];
+    trackedObjectCount: number;
+    outsideRenderableCount: number;
+}
+export interface SemanticSceneSnapshot {
+    schemaVersion: 1;
+    scene: unknown[];
+}
+export interface PersistenceChange {
+    path: string;
+    before: unknown;
+    after: unknown;
+}
+export interface PersistenceReport {
+    ok: boolean;
+    status: 'pass' | 'fail';
+    summary: string;
+    issues: AuthoringValidationIssue[];
+    changes: PersistenceChange[];
+    beforeBytes: number;
+    afterBytes: number;
+}
+type ViewerLike = Pick<ThreeViewer, 'scene'>;
+type SceneLike = IObject3D & {
+    modelRoot: IObject3D;
+    mainCamera?: IObject3D;
+    defaultCamera?: IObject3D;
+};
+/** Validate the stopped authoring hierarchy, its sources, previews, and saved camera. */
+export declare function authoringQualityReport(viewer: ViewerLike): AuthoringQualityReport;
+/** Validate that Play-only content was removed and its authored sources stayed valid. */
+export declare function runtimeCleanupReport(viewer: ViewerLike): RuntimeCleanupReport;
+/** Capture the supported saved semantics without transient engine identities. */
+export declare function semanticSceneSnapshot(source: ViewerLike | SceneLike): SemanticSceneSnapshot;
+/** Compare names, transforms, component state, and authored source relationships. */
+export declare function persistenceReport(before: unknown, after: unknown): PersistenceReport;
+export interface GameValidationResult {
+    status: 'pass' | 'fail';
+    summary: string;
+    checks?: Record<string, boolean | number | string>;
+}
+export interface GameValidationReport {
+    ok: boolean;
+    status: 'pass' | 'fail';
+    summary: string;
+    results: GameValidationResult[];
+}
+export type GameValidationFunction = () => GameValidationResult | boolean | void | Promise<GameValidationResult | boolean | void>;
+interface GameHookHost {
+    registerGameValidation(fn: GameValidationFunction): () => void;
+    publishGameTelemetry(value: object): () => void;
+    runGameValidation(): Promise<GameValidationReport>;
+    dispose(): void;
+}
+/** Register a project-defined gameplay assertion for the currently starting game. */
+export declare function registerGameValidation(fn: GameValidationFunction): () => void;
+/** Publish an immutable telemetry snapshot on window.kite3dGame.telemetry. */
+export declare function publishGameTelemetry(value: object): () => void;
+/** Install the per-createGame hook host before project modules are evaluated. */
+export declare function installGameHooks(): GameHookHost;
+declare global {
+    interface Window {
+        kite3dGame?: Readonly<{
+            readonly telemetry: object | undefined;
+            validate(): Promise<GameValidationReport>;
+        }>;
+    }
+}
+export {};