Skip to content

armgit / kiln

Public Imported from GitHub
0

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.

fix(composer): preserve render provenance (#30)

Matthew Kissinger1cbb275d455f
diff --git a/src/__tests__/composer-run-port.test.ts b/src/__tests__/composer-run-port.test.ts
index 5e3fd40d..db0ea7fa 100644
--- a/src/__tests__/composer-run-port.test.ts
+++ b/src/__tests__/composer-run-port.test.ts
@@ -10,12 +10,13 @@
import { describe, expect, test } from 'bun:test';
import type { Message, ModelStreamEvent, StreamOptions } from '@strands-agents/sdk';
-import type {
- CatalogEntry,
- PbrRenderPort,
- PbrRenderRequest,
- PbrRenderResult,
- SceneRenderPort,
+import {
+ validatePbrRenderRequest,
+ type CatalogEntry,
+ type PbrRenderPort,
+ type PbrRenderRequest,
+ type PbrRenderResult,
+ type SceneRenderPort,
} from '../composer';
import { runKilnComposer } from '../composer/agent';
import { ScriptedModel } from '../agent/__tests__/scripted-model';
@@ -80,6 +81,67 @@ describe('composer pbrRender seam (B3a)', () => {
expect(res.viewsPng).toHaveLength(2);
});
+ test('validates and clones exact perspective camera transport without changing legacy view dirs', () => {
+ const glb = new Uint8Array([1, 2, 3]);
+ const input: PbrRenderRequest = {
+ glb,
+ width: 1280,
+ height: 720,
+ cameras: [
+ {
+ position: [12, 8, 15],
+ target: [0, 1, 0],
+ up: [0, 1, 0],
+ fovDeg: 50,
+ aspect: 16 / 9,
+ near: 0.1,
+ far: 500,
+ },
+ ],
+ lightingPresetId: 'studio-day-v2',
+ };
+ const parsed = validatePbrRenderRequest(input);
+ expect(parsed).toEqual(input);
+ expect(parsed).not.toBe(input);
+ expect(parsed.glb).toBe(glb);
+ expect(parsed.cameras).not.toBe(input.cameras);
+
+ const legacyInput: PbrRenderRequest = { glb, viewDirs: [[1, 0, 0]], size: 384 };
+ const legacy = validatePbrRenderRequest(legacyInput);
+ expect(legacy).toEqual(legacyInput);
+ expect(legacy.viewDirs).not.toBe(legacyInput.viewDirs);
+
+ expect(() =>
+ validatePbrRenderRequest({ ...input, cameras: [{ ...input.cameras![0]!, far: 0.05 }] }),
+ ).toThrow(/far/i);
+ expect(() =>
+ validatePbrRenderRequest({ ...input, cameras: [{ ...input.cameras![0]!, up: [0, 0, 0] }] }),
+ ).toThrow(/up/i);
+ expect(() =>
+ validatePbrRenderRequest({
+ ...input,
+ cameras: [{ ...input.cameras![0]!, up: [3, 1.75, 3.75] }],
+ }),
+ ).toThrow(/collinear/i);
+ expect(() => validatePbrRenderRequest({ ...input, viewDirs: [[1, 0, 0]] })).toThrow(
+ /mutually exclusive/i,
+ );
+ expect(() => validatePbrRenderRequest({ ...input, size: 720 })).toThrow(/legacy size/i);
+ expect(() => validatePbrRenderRequest({ ...input, beautySize: 1080 })).toThrow(
+ /legacy size or beautySize/i,
+ );
+ expect(() => validatePbrRenderRequest({ ...input, height: undefined })).toThrow(
+ /provided together/i,
+ );
+ expect(() =>
+ validatePbrRenderRequest({ ...input, width: undefined, height: undefined }),
+ ).toThrow(/requires width and height/i);
+ expect(() => validatePbrRenderRequest({ ...input, width: 1000 })).toThrow(/aspect/i);
+ expect(() => validatePbrRenderRequest({ ...input, lightingPresetId: ' ' })).toThrow(
+ /lightingPresetId/i,
+ );
+ });
+
test('threading pbrRender changes nothing: identical tool surface and result, port never called', async () => {
let calls = 0;
const stub: PbrRenderPort = async () => {
diff --git a/src/__tests__/composer-world-run.test.ts b/src/__tests__/composer-world-run.test.ts
index 30c5379b..09f4b09a 100644
--- a/src/__tests__/composer-world-run.test.ts
+++ b/src/__tests__/composer-world-run.test.ts
@@ -12,11 +12,13 @@ import { ScriptedModel } from '../agent/__tests__/scripted-model';
class ToolCapturingModel extends ScriptedModel {
toolNames: string[][] = [];
+ messages: Message[][] = [];
override async *stream(
messages: Message[],
options?: StreamOptions,
): AsyncIterable<ModelStreamEvent> {
this.toolNames.push((options?.toolSpecs ?? []).map(({ name }) => name));
+ this.messages.push(structuredClone(messages));
yield* super.stream(messages, options);
}
}
@@ -103,6 +105,94 @@ describe('runKilnWorldIntegration', () => {
expect(String(model.seenSystemPrompts[0])).toContain(WORLD_INTEGRATION_PROMPT_V2.slice(0, 30));
});
+ test('surfaces and returns an exact GPU receipt for persistence', async () => {
+ const receiptBase = {
+ cameras: [
+ {
+ position: [12, 8, 15] as [number, number, number],
+ target: [0, 1, 0] as [number, number, number],
+ up: [0, 1, 0] as [number, number, number],
+ fovDeg: 50,
+ aspect: 16 / 9,
+ near: 0.1,
+ far: 500,
+ },
+ ],
+ width: 1280,
+ height: 720,
+ lightingPresetId: 'studio-day-v2',
+ backend: 'vulkan',
+ rendererId: 'dawn-vulkan:test',
+ outputSha256: `sha256:${'c'.repeat(64)}` as const,
+ };
+ const model = new ToolCapturingModel([
+ { toolCalls: [{ name: 'scene_world_render' }] },
+ { toolCalls: [{ name: 'scene_world_finalize' }] },
+ { text: 'done' },
+ ]);
+ let receipt: (typeof receiptBase & { worldHash: `sha256:${string}` }) | undefined;
+ const result = await runKilnWorldIntegration({
+ model,
+ prompt: 'inspect the world',
+ world: world(),
+ render: async (request) => {
+ receipt = { ...receiptBase, worldHash: request.worldHash! };
+ return {
+ ok: true,
+ pngBase64: Buffer.from('png').toString('base64'),
+ degraded: false,
+ receipt,
+ };
+ },
+ maxSteps: 6,
+ });
+
+ expect(result.renderEvidence).toEqual([
+ {
+ worldHash: result.renderEvidence[0]!.worldHash,
+ views: 1,
+ degraded: false,
+ receipt,
+ },
+ ]);
+ const modelContext = JSON.stringify(model.messages);
+ expect(modelContext).toContain('dawn-vulkan:test');
+ expect(modelContext).toContain('outputSha256');
+ expect(modelContext).toContain('"degraded":false');
+ });
+
+ test('surfaces an ok CPU fallback as degraded evidence without inventing a receipt', async () => {
+ const model = new ToolCapturingModel([
+ { toolCalls: [{ name: 'scene_world_render' }] },
+ { text: 'done' },
+ ]);
+ const result = await runKilnWorldIntegration({
+ model,
+ prompt: 'inspect the world',
+ world: world(),
+ render: async () => ({
+ ok: true,
+ pngBase64: Buffer.from('png').toString('base64'),
+ degraded: true,
+ degradeReason: 'GPU deadline; deterministic CPU fallback',
+ }),
+ maxSteps: 4,
+ });
+
+ expect(result.renderEvidence).toEqual([
+ {
+ worldHash: result.renderEvidence[0]!.worldHash,
+ views: 1,
+ degraded: true,
+ degradeReason: 'GPU deadline; deterministic CPU fallback',
+ },
+ ]);
+ const modelContext = JSON.stringify(model.messages);
+ expect(modelContext).toContain('"degraded":true');
+ expect(modelContext).toContain('GPU deadline; deterministic CPU fallback');
+ expect(modelContext).not.toContain('outputSha256');
+ });
+
test('shares one aggregate model-call allowance across compose and integration', async () => {
const budget = createGenerationCallBudget(1);
const render: SceneRenderPort = async () => ({ ok: true });
@@ -133,4 +223,31 @@ describe('runKilnWorldIntegration', () => {
expect(integrated.callBudget).toMatchObject({ consumed: 1, remaining: 0, denied: 1 });
expect(budget.receipt()).toEqual(integrated.callBudget!);
});
+
+ test('enforces its local sub-cap without consuming the aggregate remainder', async () => {
+ const budget = createGenerationCallBudget(5);
+ const integrated = await runKilnWorldIntegration({
+ model: new ScriptedModel([
+ { toolCalls: [{ name: 'scene_world_render' }] },
+ { toolCalls: [{ name: 'scene_world_render' }] },
+ { text: 'must not dispatch' },
+ ]),
+ prompt: 'inspect twice within the integration slice',
+ world: world(),
+ render: async () => ({ ok: true }),
+ maxSteps: 2,
+ generationCallBudget: budget,
+ });
+
+ expect(integrated.capped).toBe(true);
+ expect(integrated.steps).toBe(2);
+ expect(integrated.callBudget).toMatchObject({
+ limit: 5,
+ consumed: 2,
+ remaining: 3,
+ denied: 0,
+ byRole: { author: 2 },
+ });
+ expect(budget.receipt()).toEqual(integrated.callBudget!);
+ });
});
diff --git a/src/agent/hooks.test.ts b/src/agent/hooks.test.ts
index 4cb03af2..056718b1 100644
--- a/src/agent/hooks.test.ts
+++ b/src/agent/hooks.test.ts
@@ -112,6 +112,22 @@ describe('MetricsCollector', () => {
});
});
+ test('local sub-cap stops before consuming the shared aggregate allowance', () => {
+ const budget = createGenerationCallBudget(5);
+ const integration = new MetricsCollector(undefined, 2, budget, 'author');
+ const integrationAgent = fakeAgent();
+ integration.attach(integrationAgent.agent as never);
+
+ expect(integrationAgent.modelCall().cancelled).toBe(false);
+ expect(integrationAgent.modelCall().cancelled).toBe(false);
+ const locallyExhausted = integrationAgent.modelCall();
+
+ expect(locallyExhausted.cancelled).toBe(true);
+ expect(locallyExhausted.cancelText).toContain('step cap');
+ expect(integration.wasCapped()).toBe(true);
+ expect(budget.receipt()).toMatchObject({ consumed: 2, remaining: 3, denied: 0 });
+ });
+
test('records token usage from the agent result', () => {
const m = new MetricsCollector();
m.recordResultUsage({ inputTokens: 1200, outputTokens: 340 });
diff --git a/src/agent/hooks.ts b/src/agent/hooks.ts
index 0f1418f5..f3029b67 100644
--- a/src/agent/hooks.ts
+++ b/src/agent/hooks.ts
@@ -82,10 +82,10 @@ export class MetricsCollector {
* @param onEvent - Optional live sink, fired as the loop runs (tool calls,
* model calls). Errors thrown by the sink are swallowed — a broken progress
* listener must never fail a generation.
- * @param maxSteps - Legacy per-collector cap, retained for direct callers that
- * do not inject a generation-global budget.
+ * @param maxSteps - Optional per-collector sub-cap. When a shared budget is
+ * also present, both bounds apply and the tighter remaining bound wins.
* @param generationCallBudget - Shared allowance across author, observer, and
- * repair work. It supersedes maxSteps and is consumed before dispatch.
+ * repair work. It is consumed only after the local sub-cap admits dispatch.
*/
constructor(
private readonly onEvent?: (event: KilnAgentEvent) => void,
@@ -110,33 +110,32 @@ export class MetricsCollector {
this.emit({ type: 'tool', tool: event.toolUse.name, step: this.steps });
});
const offModel = agent.addHook(AfterModelCallEvent, () => {
- this.steps += 1;
this.emit({ type: 'model_call', step: this.steps });
});
- // Hard cost cap: reserve from the shared budget before dispatch. Direct
- // legacy collectors without one retain their local maxSteps behavior.
+ // Hard cost caps: enforce the local phase allowance first, then reserve from
+ // the aggregate budget. A locally denied call must not consume or increment
+ // the shared allowance.
// The SDK ends the loop with stopReason 'endTurn' (no exception) — `capped`
// lets the caller turn that bounded stop into a clear failed generation.
- const offCap =
- this.generationCallBudget || (this.maxSteps && this.maxSteps > 0)
- ? agent.addHook(BeforeModelCallEvent, (event) => {
- if (this.generationCallBudget) {
- if (this.generationCallBudget.tryConsume(this.modelCallRole)) return;
- this.capped = true;
- const receipt = this.generationCallBudget.receipt();
- event.cancel =
- `kiln: generation model-call budget reached (${receipt.limit} aggregate calls) — ` +
- 'aborted before provider dispatch to bound cost';
- return;
- }
- if (this.steps >= this.maxSteps!) {
- this.capped = true;
- event.cancel = `kiln: agent step cap reached (${this.maxSteps} model calls) — aborted to bound cost`;
- }
- })
- : undefined;
- this.cleanups.push(offTool, offModel);
- if (offCap) this.cleanups.push(offCap);
+ const offDispatch = agent.addHook(BeforeModelCallEvent, (event) => {
+ if (this.maxSteps && this.maxSteps > 0 && this.steps >= this.maxSteps) {
+ this.capped = true;
+ event.cancel = `kiln: agent step cap reached (${this.maxSteps} model calls) — aborted to bound cost`;
+ return;
+ }
+ if (this.generationCallBudget && !this.generationCallBudget.tryConsume(this.modelCallRole)) {
+ this.capped = true;
+ const receipt = this.generationCallBudget.receipt();
+ event.cancel =
+ `kiln: generation model-call budget reached (${receipt.limit} aggregate calls) — ` +
+ 'aborted before provider dispatch to bound cost';
+ return;
+ }
+ // Count admitted provider dispatches, never the SDK's synthetic after-event
+ // for a call cancelled by one of the bounds above.
+ this.steps += 1;
+ });
+ this.cleanups.push(offTool, offModel, offDispatch);
return () => this.detach();
}
diff --git a/src/composer/agent/index.ts b/src/composer/agent/index.ts
index 0da97cd9..255692de 100644
--- a/src/composer/agent/index.ts
+++ b/src/composer/agent/index.ts
@@ -34,6 +34,7 @@ export { runKilnWorldIntegration } from './world-run';
export type {
RunKilnWorldIntegrationOptions,
RunKilnWorldIntegrationResult,
+ WorldIntegrationRenderEvidence,
} from './world-run';
export { SceneCompactionManager } from './compaction';
diff --git a/src/composer/agent/world-run.ts b/src/composer/agent/world-run.ts
index a0072495..a2ee4e39 100644
--- a/src/composer/agent/world-run.ts
+++ b/src/composer/agent/world-run.ts
@@ -17,7 +17,9 @@ import {
parseWorldDocumentV2,
PlacementModel,
type Placement,
+ type SceneRenderReceipt,
type SceneRenderPort,
+ type SceneRenderResult,
type WorldDocumentV2,
validateWorldIntegrationV2,
worldDocumentV2ToSceneModelJSON,
@@ -53,11 +55,22 @@ export interface RunKilnWorldIntegrationResult {
steps: number;
usage?: AgentUsage;
callBudget?: GenerationCallBudgetReceipt;
+ /** Every successful canonical-world render attempt, in tool-call order. */
+ renderEvidence: WorldIntegrationRenderEvidence[];
capped?: boolean;
lastText?: string;
error?: string;
}
+export interface WorldIntegrationRenderEvidence {
+ worldHash: `sha256:${string}`;
+ views: number;
+ /** Absent only for a legacy host that did not report fallback provenance. */
+ degraded?: boolean;
+ degradeReason?: string;
+ receipt?: SceneRenderReceipt;
+}
+
const empty = z.object({}).strict();
const png = (base64: string): Uint8Array => new Uint8Array(Buffer.from(base64, 'base64'));
@@ -79,6 +92,7 @@ function lifecycleTools(
state: WorldIntegrationToolState,
render: SceneRenderPort,
finalized: { value: boolean },
+ renderEvidence: WorldIntegrationRenderEvidence[],
): Tool[] {
return [
tool({
@@ -126,11 +140,13 @@ function lifecycleTools(
: result.pngBase64
? [result.pngBase64]
: [];
+ const evidence = renderEvidenceOf(worldHash, frames.length, result);
+ renderEvidence.push(evidence);
return [
...frames.map(
(frame) => new ImageBlock({ format: 'png', source: { bytes: png(frame) } }),
),
- new JsonBlock({ json: { ok: true, worldHash, views: frames.length } }),
+ new JsonBlock({ json: { ok: true, ...evidence } as unknown as JSONValue }),
] as unknown as JSONValue;
},
}),
@@ -148,6 +164,32 @@ function lifecycleTools(
];
}
+function cloneReceipt(receipt: SceneRenderReceipt): SceneRenderReceipt {
+ return {
+ ...receipt,
+ cameras: receipt.cameras.map((camera) => ({
+ ...camera,
+ position: [...camera.position],
+ target: [...camera.target],
+ up: [...camera.up],
+ })),
+ };
+}
+
+function renderEvidenceOf(
+ worldHash: `sha256:${string}`,
+ views: number,
+ result: SceneRenderResult,
+): WorldIntegrationRenderEvidence {
+ return {
+ worldHash,
+ views,
+ ...(result.degraded !== undefined ? { degraded: result.degraded } : {}),
+ ...(result.degradeReason ? { degradeReason: result.degradeReason } : {}),
+ ...(result.receipt ? { receipt: cloneReceipt(result.receipt) } : {}),
+ };
+}
+
/**
* Run the bounded post-compose integration phase over one canonical authority.
* Fresh flow: compose -> migrate v1 candidate -> run this. Refine flow: compose
@@ -159,6 +201,7 @@ export async function runKilnWorldIntegration(
): Promise<RunKilnWorldIntegrationResult> {
const state: WorldIntegrationToolState = { world: parseWorldDocumentV2(options.world) };
const finalized = { value: false };
+ const renderEvidence: WorldIntegrationRenderEvidence[] = [];
const maxSteps = options.maxSteps ?? 0;
const metrics = new MetricsCollector(
options.onEvent,
@@ -181,7 +224,7 @@ export async function runKilnWorldIntegration(
});
const tools: unknown[] = [
...mutationTools,
- ...lifecycleTools(state, options.render, finalized),
+ ...lifecycleTools(state, options.render, finalized, renderEvidence),
...(options.extraTools ?? []),
];
const agent = new Agent({
@@ -205,6 +248,7 @@ export async function runKilnWorldIntegration(
finalized: finalized.value,
toolCalls: collected.toolCalls,
steps: collected.steps,
+ renderEvidence,
...(collected.usage ? { usage: collected.usage } : {}),
...(options.generationCallBudget
? { callBudget: options.generationCallBudget.receipt() }
@@ -221,6 +265,7 @@ export async function runKilnWorldIntegration(
finalized: finalized.value,
toolCalls: collected.toolCalls,
steps: collected.steps,
+ renderEvidence,
...(collected.usage ? { usage: collected.usage } : {}),
...(options.generationCallBudget
? { callBudget: options.generationCallBudget.receipt() }
diff --git a/src/composer/render-port.ts b/src/composer/render-port.ts
index 40b99c45..8b72f982 100644
--- a/src/composer/render-port.ts
+++ b/src/composer/render-port.ts
@@ -67,6 +67,12 @@ export interface SceneRenderResult {
tris?: number;
/** Present when the host renders an immutable canonical-world milestone. */
receipt?: SceneRenderReceipt;
+ /** True when `ok:true` pixels came from a declared fallback rather than the
+ * requested renderer. Absent preserves compatibility with legacy hosts whose
+ * successful result did not report fallback provenance. */
+ degraded?: boolean;
+ /** Stable, credential-free fallback explanation. Meaningful when degraded is true. */
+ degradeReason?: string;
error?: string;
}
@@ -99,6 +105,177 @@ export interface PbrRenderRequest {
size?: number;
/** Optional larger single beauty-shot size. */
beautySize?: number;
+ /** Fully resolved perspective cameras for canonical composed-scene renders.
+ * Legacy asset sheets continue to use `viewDirs` unchanged. */
+ cameras?: ResolvedSceneCamera[];
+ /** Rectangular camera target. Both are required in camera mode and each is bounded. */
+ width?: number;
+ height?: number;
+ /** Host-owned lighting preset identity applied to the perspective render. */
+ lightingPresetId?: string;
+}
+
+const PBR_REQUEST_KEYS = new Set([
+ 'glb',
+ 'viewDirs',
+ 'size',
+ 'beautySize',
+ 'cameras',
+ 'width',
+ 'height',
+ 'lightingPresetId',
+]);
+
+function finiteTuple3(value: unknown, path: string): [number, number, number] {
+ if (
+ !Array.isArray(value) ||
+ value.length !== 3 ||
+ value.some((entry) => typeof entry !== 'number' || !Number.isFinite(entry))
+ )
+ throw new TypeError(`${path} must be a finite [x,y,z] tuple`);
+ return [value[0] as number, value[1] as number, value[2] as number];
+}
+
+function boundedPixelSize(value: unknown, path: string): number {
+ if (!Number.isInteger(value) || (value as number) < 1 || (value as number) > 4096) {
+ throw new TypeError(`${path} must be an integer in [1,4096]`);
+ }
+ return value as number;
+}
+
+/** Strict runtime validator/clone for the private GPU transport boundary. */
+export function validatePbrRenderRequest(input: unknown): PbrRenderRequest {
+ if (!input || typeof input !== 'object' || Array.isArray(input)) {
+ throw new TypeError('PbrRenderRequest must be an object');
+ }
+ const source = input as Record<string, unknown>;
+ for (const key of Object.keys(source)) {
+ if (!PBR_REQUEST_KEYS.has(key)) throw new TypeError(`PbrRenderRequest.${key} is unknown`);
+ }
+ if (!(source.glb instanceof Uint8Array) || source.glb.byteLength === 0) {
+ throw new TypeError('PbrRenderRequest.glb must be a non-empty Uint8Array');
+ }
+ const result: PbrRenderRequest = { glb: source.glb };
+ if (source.viewDirs !== undefined) {
+ if (
+ !Array.isArray(source.viewDirs) ||
+ source.viewDirs.length < 1 ||
+ source.viewDirs.length > 12
+ ) {
+ throw new TypeError('PbrRenderRequest.viewDirs must contain 1..12 directions');
+ }
+ result.viewDirs = source.viewDirs.map((value, index) => {
+ const direction = finiteTuple3(value, `PbrRenderRequest.viewDirs[${index}]`);
+ if (Math.hypot(...direction) === 0) {
+ throw new TypeError(`PbrRenderRequest.viewDirs[${index}] must be non-zero`);
+ }
+ return direction;
+ });
+ }
+ if (source.size !== undefined)
+ result.size = boundedPixelSize(source.size, 'PbrRenderRequest.size');
+ if (source.beautySize !== undefined) {
+ result.beautySize = boundedPixelSize(source.beautySize, 'PbrRenderRequest.beautySize');
+ }
+ const hasWidth = source.width !== undefined;
+ const hasHeight = source.height !== undefined;
+ if (hasWidth !== hasHeight) {
+ throw new TypeError('PbrRenderRequest.width and height must be provided together');
+ }
+ if (hasWidth) {
+ result.width = boundedPixelSize(source.width, 'PbrRenderRequest.width');
+ result.height = boundedPixelSize(source.height, 'PbrRenderRequest.height');
+ }
+ if (source.cameras !== undefined) {
+ if (source.viewDirs !== undefined) {
+ throw new TypeError('PbrRenderRequest.cameras and viewDirs are mutually exclusive');
+ }
+ if (source.size !== undefined || source.beautySize !== undefined) {
+ throw new TypeError('PbrRenderRequest camera mode cannot use legacy size or beautySize');
+ }
+ if (result.width === undefined || result.height === undefined) {
+ throw new TypeError('PbrRenderRequest camera mode requires width and height');
+ }
+ if (!Array.isArray(source.cameras) || source.cameras.length < 1 || source.cameras.length > 12) {
+ throw new TypeError('PbrRenderRequest.cameras must contain 1..12 cameras');
+ }
+ result.cameras = source.cameras.map((value, index) => {
+ if (!value || typeof value !== 'object' || Array.isArray(value)) {
+ throw new TypeError(`PbrRenderRequest.cameras[${index}] must be an object`);
+ }
+ const camera = value as Record<string, unknown>;
+ const expected = new Set(['position', 'target', 'up', 'fovDeg', 'aspect', 'near', 'far']);
+ for (const key of Object.keys(camera)) {
+ if (!expected.has(key))
+ throw new TypeError(`PbrRenderRequest.cameras[${index}].${key} is unknown`);
+ }
+ const position = finiteTuple3(camera.position, `PbrRenderRequest.cameras[${index}].position`);
+ const target = finiteTuple3(camera.target, `PbrRenderRequest.cameras[${index}].target`);
+ const up = finiteTuple3(camera.up, `PbrRenderRequest.cameras[${index}].up`);
+ if (
+ Math.hypot(position[0] - target[0], position[1] - target[1], position[2] - target[2]) === 0
+ ) {
+ throw new TypeError(`PbrRenderRequest.cameras[${index}].target must differ from position`);
+ }
+ if (Math.hypot(...up) === 0) {
+ throw new TypeError(`PbrRenderRequest.cameras[${index}].up must be non-zero`);
+ }
+ const view = [
+ target[0] - position[0],
+ target[1] - position[1],
+ target[2] - position[2],
+ ] as const;
+ 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],
+ ] as const;
+ if (Math.hypot(...cross) <= Math.hypot(...view) * Math.hypot(...up) * 1e-9) {
+ throw new TypeError(
+ `PbrRenderRequest.cameras[${index}].up must not be collinear with view`,
+ );
+ }
+ const number = (key: 'fovDeg' | 'aspect' | 'near' | 'far'): number => {
+ const parsed = camera[key];
+ if (typeof parsed !== 'number' || !Number.isFinite(parsed)) {
+ throw new TypeError(`PbrRenderRequest.cameras[${index}].${key} must be finite`);
+ }
+ return parsed;
+ };
+ const fovDeg = number('fovDeg');
+ const aspect = number('aspect');
+ const near = number('near');
+ const far = number('far');
+ if (fovDeg <= 0 || fovDeg >= 180) {
+ throw new TypeError(`PbrRenderRequest.cameras[${index}].fovDeg must be in (0,180)`);
+ }
+ if (aspect <= 0)
+ throw new TypeError(`PbrRenderRequest.cameras[${index}].aspect must be positive`);
+ if (near <= 0)
+ throw new TypeError(`PbrRenderRequest.cameras[${index}].near must be positive`);
+ if (far <= near)
+ throw new TypeError(`PbrRenderRequest.cameras[${index}].far must exceed near`);
+ const targetAspect = result.width! / result.height!;
+ if (Math.abs(aspect - targetAspect) > Math.max(1, targetAspect) * 1e-9) {
+ throw new TypeError(`PbrRenderRequest.cameras[${index}].aspect must equal width/height`);
+ }
+ return { position, target, up, fovDeg, aspect, near, far };
+ });
+ } else if (hasWidth) {
+ throw new TypeError('PbrRenderRequest width and height require camera mode');
+ }
+ if (source.lightingPresetId !== undefined) {
+ if (
+ typeof source.lightingPresetId !== 'string' ||
+ !source.lightingPresetId.trim() ||
+ source.lightingPresetId !== source.lightingPresetId.trim() ||
+ source.lightingPresetId.length > 128
+ ) {
+ throw new TypeError('PbrRenderRequest.lightingPresetId must be a non-empty string');
+ }
+ result.lightingPresetId = source.lightingPresetId;
+ }
+ return result;
}
/**