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 { createHash } from 'node:crypto';
import {
DEFAULT_PRESENTATION_PRESET_ID,
PRESENTATION_PRESET_IDS,
isPresentationPresetId,
} from './presentation-presets.mjs';
import { DEFAULT_BACKDROP_ID, backdropMessage, isBackdropId } from './backdrops.mjs';
// Singular export retained for existing Engine/Studio callers. The plural list
// is the registry-backed source of truth for strict ID validation and discovery.
export const SUPPORTED_LIGHTING_PRESET_ID = DEFAULT_PRESENTATION_PRESET_ID;
export const SUPPORTED_LIGHTING_PRESET_IDS = PRESENTATION_PRESET_IDS;
export const RENDER_FIDELITY_VERSION = 'kiln.render-fidelity.v1';
export const RENDER_FIDELITY_PRODUCER = 'kiln-render-service';
export const RENDER_OPERATIONAL_EVIDENCE_VERSION = 'kiln.render-operational.v1';
export const RENDER_OUTCOME_CODES = Object.freeze([
'health_ok',
'gpu_success',
'auth_rejected',
'request_rejected',
'not_implemented',
'route_not_found',
'render_failed',
]);
export const MAX_VIEW_DIRS = 12;
export const MAX_CAMERAS = 12;
export const MIN_CAMERA_DIMENSION = 1;
export const MAX_CAMERA_DIMENSION = 4096;
// Includes every camera in the request. This admits one 4K frame, eight 1080p
// frames, or twelve 720p frames while bounding transient MSAA/depth allocation.
export const MAX_CAMERA_TOTAL_PIXELS = 16_777_216;
export const DEFAULT_VIEW_DIRS = Object.freeze([
Object.freeze([1, 0.35, 1]),
Object.freeze([-1, 0.35, 1]),
Object.freeze([1, 0.35, -1]),
Object.freeze([-1, 0.35, -1]),
Object.freeze([0, 1, 0.001]),
Object.freeze([0.001, -1, 0.001]),
]);
function badRequest(message) {
return Object.assign(new Error(message), { status: 400 });
}
function supportedPresetMessage(field) {
return SUPPORTED_LIGHTING_PRESET_IDS.length === 1
? `${field} must be ${SUPPORTED_LIGHTING_PRESET_ID}`
: `${field} must be one of: ${SUPPORTED_LIGHTING_PRESET_IDS.join(', ')}`;
}
const RENDER_OUTCOME_CODE_SET = new Set(RENDER_OUTCOME_CODES);
const MAX_OPERATIONAL_MS = 86_400_000;
const MAX_OPERATIONAL_QUEUE_DEPTH = 10_000;
const OPERATIONAL_EVIDENCE_KEYS = new Set([
'outcomeCode',
'queueWaitMs',
'queueDepthAtEnqueue',
'concurrencyAtStart',
'firstRenderInProcess',
'workerAgeMsAtStart',
]);
/** Stable low-cardinality outcome for structured request logs and metrics extraction. */
export function httpRenderOutcomeCode({ method, path, status }) {
if (status === 401) return 'auth_rejected';
if (status === 501) return 'not_implemented';
if (status === 404) return 'route_not_found';
if ([400, 408, 413, 499, 503].includes(status)) return 'request_rejected';
if (
method === 'GET' &&
(path === '/health' || path === '/ping') &&
status >= 200 &&
status < 300
) {
return 'health_ok';
}
if (method === 'POST' && path === '/render' && status >= 200 && status < 300) {
return 'gpu_success';
}
return 'render_failed';
}
function nonNegativeFinite(value, path) {
if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
throw badRequest(`${path} must be a non-negative finite number`);
}
return value;
}
/**
* Produce the bounded, identifier-free queue/worker envelope consumed by R2.8
* metrics extraction. Oversized valid observations are capped rather than
* failing a completed render; malformed internal values still fail closed.
*/
export function buildRenderOperationalEvidenceV1(input) {
if (!input || typeof input !== 'object' || Array.isArray(input)) {
throw badRequest('render operational evidence must be an object');
}
for (const key of Object.keys(input)) {
if (!OPERATIONAL_EVIDENCE_KEYS.has(key)) throw badRequest(`${key} is unknown`);
}
if (!RENDER_OUTCOME_CODE_SET.has(input.outcomeCode)) {
throw badRequest('outcomeCode is not supported');
}
const queueWaitMs = nonNegativeFinite(input.queueWaitMs, 'queueWaitMs');
const workerAgeMsAtStart = nonNegativeFinite(input.workerAgeMsAtStart, 'workerAgeMsAtStart');
if (!Number.isInteger(input.queueDepthAtEnqueue) || input.queueDepthAtEnqueue < 0) {
throw badRequest('queueDepthAtEnqueue must be a non-negative integer');
}
if (input.concurrencyAtStart !== 1) {
throw badRequest('concurrencyAtStart must be 1 for the serial GPU queue');
}
if (typeof input.firstRenderInProcess !== 'boolean') {
throw badRequest('firstRenderInProcess must be boolean');
}
const evidenceClamped =
queueWaitMs > MAX_OPERATIONAL_MS ||
workerAgeMsAtStart > MAX_OPERATIONAL_MS ||
input.queueDepthAtEnqueue > MAX_OPERATIONAL_QUEUE_DEPTH;
return {
version: RENDER_OPERATIONAL_EVIDENCE_VERSION,
outcomeCode: input.outcomeCode,
queueWaitMs: +Math.min(queueWaitMs, MAX_OPERATIONAL_MS).toFixed(1),
queueDepthAtEnqueue: Math.min(input.queueDepthAtEnqueue, MAX_OPERATIONAL_QUEUE_DEPTH),
concurrencyAtStart: 1,
concurrencyLimit: 1,
workerPhase: input.firstRenderInProcess ? 'first-render' : 'warm-render',
workerAgeMsAtStart: +Math.min(workerAgeMsAtStart, MAX_OPERATIONAL_MS).toFixed(1),
evidenceClamped,
};
}
export { createBoundedRenderQueue as createSerialRenderQueue } from './render-queue.mjs';
function finiteTuple3(value, path) {
if (!Array.isArray(value) || value.length !== 3 || !value.every(Number.isFinite)) {
throw badRequest(`${path} must be [x,y,z] finite numbers`);
}
return [...value];
}
function finiteNumber(value, path) {
if (!Number.isFinite(value)) throw badRequest(`${path} must be finite`);
return value;
}
function pixelDimension(value, path) {
if (!Number.isInteger(value) || value < MIN_CAMERA_DIMENSION || value > MAX_CAMERA_DIMENSION) {
throw badRequest(
`${path} must be an integer in [${MIN_CAMERA_DIMENSION},${MAX_CAMERA_DIMENSION}]`,
);
}
return value;
}
/** Legacy direction validation. Returned arrays are cloned; defaults are mutable copies. */
export function validateViewDirs(views) {
if (views === undefined || views === null || (Array.isArray(views) && views.length === 0)) {
return DEFAULT_VIEW_DIRS.map((view) => [...view]);
}
if (!Array.isArray(views)) throw badRequest('views must be an array of [x,y,z] directions');
if (views.length > MAX_VIEW_DIRS) {
throw badRequest(`views has ${views.length} entries; the maximum is ${MAX_VIEW_DIRS}`);
}
return views.map((value, index) => {
const direction = finiteTuple3(value, `views[${index}]`);
if (Math.hypot(...direction) < 1e-9) {
throw badRequest(`views[${index}] must not be the zero vector`);
}
return direction;
});
}
/** Strict camera-mode parser shared by HTTP and direct renderer callers. */
export function validateCameraMode(input) {
if (!input || typeof input !== 'object' || Array.isArray(input)) {
throw badRequest('camera render options must be an object');
}
if (
!Array.isArray(input.cameras) ||
input.cameras.length < 1 ||
input.cameras.length > MAX_CAMERAS
) {
throw badRequest(`cameras must contain 1..${MAX_CAMERAS} entries`);
}
const width = pixelDimension(input.width, 'width');
const height = pixelDimension(input.height, 'height');
const totalPixels = width * height * input.cameras.length;
if (!Number.isSafeInteger(totalPixels) || totalPixels > MAX_CAMERA_TOTAL_PIXELS) {
throw badRequest(
`camera request has ${totalPixels} total pixels; maximum is ${MAX_CAMERA_TOTAL_PIXELS}`,
);
}
const targetAspect = width / height;
const cameras = input.cameras.map((value, index) => {
if (!value || typeof value !== 'object' || Array.isArray(value)) {
throw badRequest(`cameras[${index}] must be an object`);
}
const allowed = new Set([
'position',
'target',
'up',
'fovDeg',
'aspect',
'near',
'far',
'version',
'projection',
'halfHeight',
]);
for (const key of Object.keys(value)) {
if (!allowed.has(key)) throw badRequest(`cameras[${index}].${key} is unknown`);
}
const position = finiteTuple3(value.position, `cameras[${index}].position`);
const target = finiteTuple3(value.target, `cameras[${index}].target`);
const up = finiteTuple3(value.up, `cameras[${index}].up`);
const view = target.map((component, axis) => component - position[axis]);
const viewLength = Math.hypot(...view);
const upLength = Math.hypot(...up);
if (viewLength < 1e-9) throw badRequest(`cameras[${index}].target must differ from position`);
if (upLength < 1e-9) throw badRequest(`cameras[${index}].up must be non-zero`);
const cross = [
view[1] * up[2] - view[2] * up[1],
view[2] * up[0] - view[0] * up[2],
view[0] * up[1] - view[1] * up[0],
];
if (Math.hypot(...cross) <= viewLength * upLength * 1e-9) {
throw badRequest(`cameras[${index}].up must not be collinear with view`);
}
const versioned = value.version !== undefined || value.projection !== undefined;
if (
versioned &&
(value.version !== 'kiln.camera.v1' ||
!['orthographic', 'perspective'].includes(value.projection))
)
throw badRequest('invalid versioned camera');
const orthographic = value.projection === 'orthographic';
if (orthographic && value.fovDeg !== undefined)
throw badRequest('orthographic camera cannot use fovDeg');
if (!orthographic && value.halfHeight !== undefined)
throw badRequest('perspective camera cannot use halfHeight');
const halfHeight = orthographic
? finiteNumber(value.halfHeight, `cameras[${index}].halfHeight`)
: undefined;
if (orthographic && halfHeight <= 0) throw badRequest('halfHeight must be positive');
const fovDeg = orthographic
? undefined
: finiteNumber(value.fovDeg, `cameras[${index}].fovDeg`);
const aspect = finiteNumber(value.aspect, `cameras[${index}].aspect`);
const near = finiteNumber(value.near, `cameras[${index}].near`);
const far = finiteNumber(value.far, `cameras[${index}].far`);
if (!orthographic && (fovDeg <= 0 || fovDeg >= 180)) {
throw badRequest(`cameras[${index}].fovDeg must be in (0,180)`);
}
if (aspect <= 0) throw badRequest(`cameras[${index}].aspect must be positive`);
if (near <= 0) throw badRequest(`cameras[${index}].near must be positive`);
if (far <= near) throw badRequest(`cameras[${index}].far must exceed near`);
if (Math.abs(aspect - targetAspect) > Math.max(1, targetAspect) * 1e-9) {
throw badRequest(`cameras[${index}].aspect must equal width/height`);
}
return {
position,
target,
up,
...(orthographic ? { halfHeight } : { fovDeg }),
aspect,
near,
far,
...(versioned ? { version: value.version, projection: value.projection } : {}),
};
});
const lightingPresetId =
input.lightingPresetId === undefined ? SUPPORTED_LIGHTING_PRESET_ID : input.lightingPresetId;
if (!isPresentationPresetId(lightingPresetId)) {
throw badRequest(supportedPresetMessage('lighting_preset_id'));
}
return { cameras, width, height, lightingPresetId, totalPixels };
}
/** Parse only render-mode fields; GLB/auth/body-size validation remains in the server. */
export function validateRenderMode(body) {
if (!body || typeof body !== 'object' || Array.isArray(body)) {
throw badRequest('render body must be an object');
}
// The legacy free-hex `background` is gone from both modes: a colour the
// engine's CPU rasterizer would not also paint breaks the agreement the named
// backdrop table exists for. Both modes take `backdrop`; omitted is neutral.
if (body.background !== undefined) {
throw badRequest('background is not accepted; name a backdrop instead: neutral, dark, light');
}
if (body.cameras !== undefined) {
if (body.views !== undefined || body.size !== undefined || body.beauty_size !== undefined) {
throw badRequest('camera mode is mutually exclusive with views, size, and beauty_size');
}
const allowed = new Set([
'glb_base64',
'input_glb_sha256',
'cameras',
'width',
'height',
'lighting_preset_id',
'backdrop',
]);
for (const key of Object.keys(body)) {
if (body[key] !== undefined && !allowed.has(key)) {
throw badRequest(`camera mode field ${key} is unknown`);
}
}
const camera = validateCameraMode({
cameras: body.cameras,
width: body.width,
height: body.height,
lightingPresetId: body.lighting_preset_id,
});
return { mode: 'camera', ...camera, backdrop: validateBackdrop(body.backdrop) };
}
if (
body.width !== undefined ||
body.height !== undefined ||
body.lighting_preset_id !== undefined
) {
throw badRequest('width, height, and lighting_preset_id require cameras');
}
return {
mode: 'legacy',
viewDirs: validateViewDirs(body.views),
size: body.size,
beautySize: body.beauty_size,
backdrop: validateBackdrop(body.backdrop),
};
}
/**
* A named backdrop from the shared table, accepted in both modes. It cannot name
* a colour the engine's CPU rasterizer would not also paint, so it is safe in
* exact camera mode too. Omitted means the neutral entry.
*/
function validateBackdrop(value) {
if (value === undefined) return DEFAULT_BACKDROP_ID;
if (!isBackdropId(value)) throw badRequest(backdropMessage('backdrop'));
return value;
}
export function sha256(bytes) {
return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
}
const SHA256_IDENTITY_RE = /^sha256:[0-9a-f]{64}$/;
/**
* Compute the identity of the exact GLB bytes the renderer will consume. A new
* caller may also assert its expected identity; legacy callers omit the claim
* and still receive the computed identity in the response.
*/
export function validateInputGlbIdentity(bytes, claimedIdentity) {
if (!(bytes instanceof Uint8Array) || bytes.byteLength === 0) {
throw badRequest('GLB identity requires non-empty bytes');
}
const actual = sha256(bytes);
if (claimedIdentity === undefined) return actual;
if (typeof claimedIdentity !== 'string' || !SHA256_IDENTITY_RE.test(claimedIdentity)) {
throw badRequest('input_glb_sha256 must be sha256:<64 lowercase hex characters>');
}
if (claimedIdentity !== actual) {
throw badRequest('input_glb_sha256 does not match glb_base64 bytes');
}
return actual;
}
const FIDELITY_TIMING_KEYS = new Set([
'loadMs',
'viewsMs',
'beautyMs',
'totalMs',
'queueWaitMs',
'queueAndTotalMs',
]);
function cloneCamera(camera) {
return {
position: [...camera.position],
target: [...camera.target],
up: [...camera.up],
...(camera.projection === 'orthographic'
? { halfHeight: camera.halfHeight }
: { fovDeg: camera.fovDeg }),
aspect: camera.aspect,
near: camera.near,
far: camera.far,
...(camera.version ? { version: camera.version, projection: camera.projection } : {}),
};
}
/**
* Mint the additive renderer-side fidelity receipt only after all identity and
* camera/profile claims have been checked against the request and actual result.
*
* `exactArtifact` is deliberately false: this service attests the exact GLB
* bytes it rendered, but only the caller knows whether those bytes are the
* persisted/final artifact rather than an in-loop or derivative GLB.
*/
export function buildRenderFidelityV1({
rendererId,
inputGlbSha256,
presentationProfile,
renderMode,
resolvedCameras,
timings,
}) {
if (
typeof rendererId !== 'string' ||
rendererId.trim() !== rendererId ||
rendererId.length < 1 ||
rendererId.length > 160
) {
throw badRequest('rendererId must be a non-empty string of at most 160 characters');
}
if (typeof inputGlbSha256 !== 'string' || !SHA256_IDENTITY_RE.test(inputGlbSha256)) {
throw badRequest('inputGlbSha256 must be sha256:<64 lowercase hex characters>');
}
if (!isPresentationPresetId(presentationProfile)) {
throw badRequest(supportedPresetMessage('presentationProfile'));
}
if (!renderMode || (renderMode.mode !== 'camera' && renderMode.mode !== 'legacy')) {
throw badRequest('renderMode must be a validated camera or legacy render mode');
}
if (!Array.isArray(resolvedCameras)) {
throw badRequest('resolvedCameras must be an array');
}
const requestedCameras = renderMode.mode === 'camera' ? renderMode.cameras.map(cloneCamera) : [];
if (
resolvedCameras.length !== requestedCameras.length ||
JSON.stringify(resolvedCameras) !== JSON.stringify(requestedCameras)
) {
throw badRequest('resolved cameras do not match the validated requested cameras');
}
if (!timings || typeof timings !== 'object' || Array.isArray(timings)) {
throw badRequest('timings must be an object');
}
const checkedTimings = {};
for (const [key, value] of Object.entries(timings)) {
if (!FIDELITY_TIMING_KEYS.has(key)) throw badRequest(`timings.${key} is unknown`);
if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
throw badRequest(`timings.${key} must be a non-negative finite number`);
}
checkedTimings[key] = value;
}
if (checkedTimings.totalMs === undefined || checkedTimings.queueAndTotalMs === undefined) {
throw badRequest('timings must include totalMs and queueAndTotalMs');
}
if (checkedTimings.queueAndTotalMs < checkedTimings.totalMs) {
throw badRequest('timings.queueAndTotalMs must be at least totalMs');
}
if (
checkedTimings.queueWaitMs !== undefined &&
checkedTimings.queueWaitMs > checkedTimings.queueAndTotalMs
) {
throw badRequest('timings.queueWaitMs must not exceed queueAndTotalMs');
}
return {
version: RENDER_FIDELITY_VERSION,
producer: RENDER_FIDELITY_PRODUCER,
requested: 'full-preferred',
delivered: 'full-material',
materialFaithful: true,
exactArtifact: false,
rendererId,
inputGlbSha256,
degraded: false,
presentationProfile,
renderMode: renderMode.mode,
requestedCameras,
resolvedCameras: resolvedCameras.map(cloneCamera),
timings: checkedTimings,
};
}
/** Canonical identity of an ordered output set; it is not a composite-image hash. */
export function outputSetSha256(outputs) {
const hash = createHash('sha256');
hash.update('kiln-render-output-set-v1\0');
for (const output of outputs) {
const size = Buffer.allocUnsafe(4);
size.writeUInt32BE(output.byteLength);
hash.update(size);
hash.update(output);
}
return `sha256:${hash.digest('hex')}`;
}