Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
import { useEffect } from 'react';
import { useRuntime, type SceneRuntime } from '../internal/runtime';
import { rendererProgramCounts } from './counts';
import { KIT_DEV_PARAMS, readDevParams, FrameTimeRecorder } from './core';
import type { DeviceProbe } from '../quality/core';
import { createRenderProbe, type ProbeOptions } from './probe';
export * from './core';
const live=new Set<SceneRuntime>();
const context=(runtime?:SceneRuntime)=>runtime??Array.from(live).at(-1);
export function registerTestHooks(hooks:Record<string,(...args:any[])=>unknown>,runtime?:SceneRuntime):()=>void{
if(!(import.meta.env.KILN_TEST||import.meta.env.KILN_DEV))return()=>{};
const rt=context(runtime);if(!rt)return()=>{};Object.assign(rt.testHooks,hooks);
return()=>{for(const [name,fn]of Object.entries(hooks))if(rt.testHooks[name]===fn)delete rt.testHooks[name];};
}
export function useRegisterTestHooks(hooks:Record<string,(...args:any[])=>unknown>):void{const rt=useRuntime();useEffect(()=>registerTestHooks(hooks,rt),[rt,hooks]);}
export function registerWorkload(name:string,fn:(phase:number)=>void,runtime?:SceneRuntime):()=>void{
if(!(import.meta.env.KILN_TEST||import.meta.env.KILN_DEV))return()=>{};
const rt=context(runtime);rt?.workloads.set(name,fn);return()=>{if(rt?.workloads.get(name)===fn)rt.workloads.delete(name);};
}
/**
* B-10 hook (SPEC 18): Chrome cannot emulate GPU adapter strings, so a test or dev page may set
* `window.__kilnProbeOverride` (a partial DeviceProbe) before mounting. The kit merges it over the measured
* probe before classification; an `adapter` in the override replaces the measured adapter strings entirely.
* Public builds never read it (the call site is behind the test/dev flags).
*/
export function applyProbeOverride(probe:DeviceProbe):DeviceProbe{
if(!(import.meta.env.KILN_TEST||import.meta.env.KILN_DEV))return probe;
const override=(window as unknown as {__kilnProbeOverride?:Partial<DeviceProbe>}).__kilnProbeOverride;
if(!override||typeof override!=='object')return probe;
return {...probe,...override,adapter:override.adapter?{vendor:'',architecture:'',device:'',description:'',...(override.adapter as Partial<NonNullable<DeviceProbe['adapter']>>)}:probe.adapter};
}
export function installTestHooks(runtime:SceneRuntime) {
if(!(import.meta.env.KILN_TEST||import.meta.env.KILN_DEV))return()=>{};
live.add(runtime);const recorder=new FrameTimeRecorder(),cpuRecorder=new FrameTimeRecorder(),events:unknown[]=[];let waitSerial=0;
const pending=new Set<(error:Error)=>void>();let observer:PerformanceObserver|null=null;
const measurement=(on:boolean)=>{
recorder.enabled=cpuRecorder.enabled=on;runtime.data.set('measure',on);
if(on){recorder.clear();cpuRecorder.clear();runtime.data.set('longTasks',0);
if(typeof PerformanceObserver!=='undefined'&&PerformanceObserver.supportedEntryTypes.includes('longtask')){
observer?.disconnect();observer=new PerformanceObserver(list=>runtime.data.set('longTasks',Number(runtime.data.get('longTasks')??0)+list.getEntries().length));observer.observe({type:'longtask'});
}
}else{observer?.disconnect();observer=null;}
};
runtime.data.set('cpuRecorder',cpuRecorder);
runtime.data.set('recorder',recorder);runtime.data.set('events',events);
runtime.devParams=readDevParams(KIT_DEV_PARAMS);
if(typeof runtime.devParams.time==='number'){runtime.clock.time=runtime.clock.ambient=runtime.devParams.time;runtime.clock.timeScale=0;}
if(runtime.devParams.freeze)runtime.clock.timeScale=0;
if((window as unknown as {__kilnMeasureRequested?:boolean}).__kilnMeasureRequested){runtime.data.set('startupAt',performance.now());measurement(true);}
const probe=createRenderProbe(runtime);
const api={
whenReady:()=>runtime.ready?Promise.resolve():new Promise<void>((accept,reject)=>{
if(runtime.failed||runtime.disposed){reject(new Error('Scene did not become ready'));return;}
const stop=runtime.subscribe(()=>{if(runtime.ready){stop();pending.delete(fail);accept();}else if(runtime.failed||runtime.disposed)fail(new Error('Scene did not become ready'));});
const fail=(error:Error)=>{stop();pending.delete(fail);reject(error);};pending.add(fail);
}),
waitFrames:(n:number)=>new Promise<void>((accept,reject)=>{
if(runtime.disposed){reject(new Error('Scene disposed'));return;}if(n<=0){accept();return;}
const target=runtime.clock.frame+n;const stop=runtime.systems.add('wait-'+(++waitSerial),10000,()=>{if(runtime.clock.frame>=target){stop();pending.delete(fail);accept();}});
const fail=(error:Error)=>{stop();pending.delete(fail);reject(error);};pending.add(fail);
}),
stats:()=>{const info=runtime.renderer?.info;return{frame:info?.frame??0,render:info?{calls:info.render.calls,frame:info.frame,drawCalls:info.render.drawCalls,triangles:info.render.triangles}:null,memory:info?{...info.memory}:null,...rendererProgramCounts(runtime.renderer as any),resources:runtime.registry.size,cpuRenderMedianMs:cpuRecorder.values().length?cpuRecorder.summary().medianMs:null,longTasks:runtime.data.get('longTasks')??null,readyMs:runtime.data.get('readyMs')??null,...Object.fromEntries(Object.entries(runtime.testHooks).filter(([name])=>name==='counts').map(([name,fn])=>[name,fn()]))};},
frameTimes:()=>recorder.values(),cpuRenderTimes:()=>cpuRecorder.values(),recordFrames:measurement,beginMeasurement:()=>measurement(true),
feedFrameTimes:(trace:number[])=>{runtime.data.set('syntheticGovernor',true);const changes=[];for(const dt of trace){const result=runtime.quality?.step(dt,{paused:false,hidden:false});if(result)changes.push(result);}return changes;},
tierState:()=>runtime.quality?{tier:runtime.quality.tier,level:runtime.quality.level,live:{...runtime.quality.live},device:runtime.quality.device,knobs:runtime.quality.knobs,probe:runtime.data.get('probe')??null,locked:runtime.quality.governor.locked}:null,
motionPolicy:()=>({...runtime.motion,paused:runtime.paused,time:runtime.clock.time,ambient:runtime.clock.ambient}),
setTime:(time:number)=>{runtime.clock.time=runtime.clock.ambient=time;},
setTimeScale:(scale:number)=>{runtime.clock.timeScale=scale;},
setPlaying:runtime.setPlaying,
setDpr:(dpr:number)=>runtime.state?.setDpr(dpr),
runWorkload:(name:string)=>{runtime.data.set('workload',name);},
events,
invoke:(name:string,...args:unknown[])=>runtime.testHooks[name]?.(...args),
// S1 count probe (probe.ts): per-pass draws, triangles and pipelines once K frames agree, with count-only what-ifs.
// `timeoutMs` cancels the probe in the page (restoring its what-if), so a caller's own timeout never leaves one running.
probeFrames:({timeoutMs,...options}:ProbeOptions&{timeoutMs?:number}={})=>new Promise((accept,reject)=>{
if(runtime.disposed){reject(new Error('Scene disposed'));return;}
let cancel=()=>{},timer:ReturnType<typeof setTimeout>|undefined;
const settle=()=>{clearTimeout(timer);pending.delete(fail);},fail=(error:Error)=>{cancel();settle();reject(error);};
try{cancel=probe.run(options,result=>{settle();accept({...result,tier:api.tierState()});},error=>{settle();reject(error);});}catch(error){reject(error);return;}
pending.add(fail);
if(timeoutMs!==undefined)timer=setTimeout(()=>fail(new Error(`probeFrames timed out after ${timeoutMs} ms`)),timeoutMs);
}),
sceneSummary:()=>probe.sceneSummary(),
get frame(){return runtime.clock.frame;},
get disposed(){return runtime.disposed;},
};
const proxy=new Proxy(api,{get(target,key,receiver){if(typeof key==='string'&&runtime.testHooks[key])return runtime.testHooks[key];return Reflect.get(target,key,receiver);}});
const win=window as unknown as {__kilnScene?:typeof proxy};win.__kilnScene=proxy;
return()=>{for(const fail of pending)fail(new Error('Scene disposed'));pending.clear();observer?.disconnect();live.delete(runtime);runtime.testHooks={};runtime.workloads.clear();recorder.clear();cpuRecorder.clear();runtime.data.delete('recorder');runtime.data.delete('cpuRecorder');if(win.__kilnScene===proxy)delete win.__kilnScene;};
}
export function fakeMatchMedia(matches:Record<string,boolean>={}) {
const entries=new Map<string,{matches:boolean;listeners:Set<(event:{matches:boolean;media:string})=>void>}>();
const matchMedia=(media:string)=>{let entry=entries.get(media);if(!entry){entry={matches:matches[media]??false,listeners:new Set()};entries.set(media,entry);}return{media,get matches(){return entry!.matches;},onchange:null,addEventListener:(_type:string,fn:any)=>entry!.listeners.add(fn),removeEventListener:(_type:string,fn:any)=>entry!.listeners.delete(fn),addListener:(fn:any)=>entry!.listeners.add(fn),removeListener:(fn:any)=>entry!.listeners.delete(fn),dispatchEvent:()=>true} as MediaQueryList;};
return{matchMedia,set(media:string,value:boolean){matchMedia(media);const entry=entries.get(media)!;entry.matches=value;for(const fn of entry.listeners)fn({media,matches:value});}};
}