@forgeax/engine-app 0.0.0-dev.8d955ade1c79

package/src/tool-preview/evidence.ts

@@ -0,0 +1,59 @@
+import {
+  type ArtifactRef,
+  createArtifactRef,
+  type PreviewArtifactManifest,
+  type PreviewArtifactRole,
+  type SnapshotRef,
+  snapshotStaleError,
+  type ToolRuntimeError,
+  validatePreviewArtifactManifest,
+} from '@forgeax/engine-tool-runtime';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type { ToolPreviewTrace } from './recipe';
+
+export interface ToolPreviewEvidence {
+  readonly trace: ToolPreviewTrace;
+  readonly artifacts: readonly ArtifactRef[];
+  readonly manifest?: PreviewArtifactManifest;
+}
+
+export function joinToolPreviewEvidence(input: {
+  readonly trace: ToolPreviewTrace;
+  readonly manifest: PreviewArtifactManifest;
+  readonly required: readonly PreviewArtifactRole[];
+}): Result<ToolPreviewEvidence, ToolRuntimeError> {
+  const validated = validatePreviewArtifactManifest(input.manifest, input.required);
+  if (!validated.ok) return err(validated.error);
+  const artifacts = input.manifest.artifacts.map((artifact) =>
+    createArtifactRef({
+      kind:
+        artifact.kind === 'report' || artifact.kind === 'contact-sheet'
+          ? 'tool-result'
+          : artifact.kind,
+      digest: artifact.digest,
+      uri: artifact.uri,
+      mediaType: artifact.mediaType,
+      sizeBytes: artifact.byteLength,
+    }),
+  );
+  return ok({ trace: input.trace, artifacts, manifest: input.manifest });
+}
+
+export function createToolPreviewEvidence(
+  trace: ToolPreviewTrace,
+  artifacts: readonly ArtifactRef[],
+): ToolPreviewEvidence {
+  return { trace, artifacts: [...artifacts] };
+}
+
+export function joinResourcePreviewEvidence(input: {
+  readonly snapshot: SnapshotRef;
+  readonly manifest: PreviewArtifactManifest;
+  readonly requiredRoles: readonly PreviewArtifactRole[];
+}): Result<PreviewArtifactManifest, ToolRuntimeError> {
+  if (input.manifest.identity.snapshotDigest !== input.snapshot.digest) {
+    return err(snapshotStaleError(input.snapshot.digest, input.manifest.identity.snapshotDigest));
+  }
+  const validated = validatePreviewArtifactManifest(input.manifest, input.requiredRoles);
+  return validated.ok ? ok(validated.value) : err(validated.error);
+}

package/src/tool-preview/framing.ts

@@ -0,0 +1,52 @@
+export interface ToolPreviewCameraFrame {
+  readonly center: readonly [number, number, number];
+  readonly radius: number;
+  readonly distance: number;
+  readonly near: number;
+  readonly far: number;
+}
+
+export function fitToolPreviewCameraToAabb(
+  aabb: readonly [number, number, number, number, number, number],
+  options: { readonly aspect: number; readonly fov: number; readonly padding?: number },
+): ToolPreviewCameraFrame {
+  const [minX, minY, minZ, maxX, maxY, maxZ] = aabb;
+  if (
+    ![minX, minY, minZ, maxX, maxY, maxZ].every(Number.isFinite) ||
+    minX > maxX ||
+    minY > maxY ||
+    minZ > maxZ ||
+    !Number.isFinite(options.aspect) ||
+    options.aspect <= 0 ||
+    !Number.isFinite(options.fov) ||
+    options.fov <= 0 ||
+    options.fov >= Math.PI
+  ) {
+    throw new TypeError('tool preview camera framing requires a finite AABB, aspect, and FOV');
+  }
+  const center: readonly [number, number, number] = [
+    (minX + maxX) / 2,
+    (minY + maxY) / 2,
+    (minZ + maxZ) / 2,
+  ];
+  const radius = Math.max(
+    Math.hypot((maxX - minX) / 2, (maxY - minY) / 2, (maxZ - minZ) / 2),
+    0.001,
+  );
+  const verticalHalfFov = options.fov / 2;
+  const horizontalHalfFov = Math.atan(Math.tan(verticalHalfFov) * options.aspect);
+  const limitingHalfFov = Math.min(verticalHalfFov, horizontalHalfFov);
+  const padding = options.padding ?? 1.15;
+  if (!Number.isFinite(padding) || padding < 1) {
+    throw new TypeError('tool preview camera framing padding must be finite and at least one');
+  }
+  const distance = (radius / Math.sin(limitingHalfFov)) * padding;
+  const depthMargin = radius * (padding - 1);
+  return {
+    center,
+    radius,
+    distance,
+    near: Math.max(0.001, distance - radius - depthMargin),
+    far: distance + radius + depthMargin,
+  };
+}

package/src/tool-preview/recipe.ts

@@ -0,0 +1,137 @@
+import { isSerializableValue, type JsonValue } from '@forgeax/engine-tool-runtime';
+
+export type ToolPreviewPresentation = 'hidden' | 'visible';
+
+export interface ToolPreviewAction {
+  readonly frame: number;
+  readonly name: string;
+  readonly value?: JsonValue;
+}
+
+export interface ToolPreviewRecipe {
+  readonly backend: 'webgpu';
+  readonly presentation: ToolPreviewPresentation;
+  readonly viewport: { readonly width: number; readonly height: number };
+  readonly actions: readonly ToolPreviewAction[];
+  readonly deltaSeconds: number;
+  readonly frames: number;
+}
+
+export interface ToolPreviewRecipeOptions {
+  readonly backend?: 'webgpu' | 'rhi-null' | string;
+  readonly presentation?: ToolPreviewPresentation;
+  readonly viewport?: { readonly width: number; readonly height: number };
+  readonly actions?: readonly ToolPreviewAction[];
+  readonly deltaSeconds?: number;
+  readonly frames?: number;
+}
+
+export type ToolPreviewTraceEvent =
+  | 'canvas-created'
+  | 'rhi-debug-armed'
+  | 'renderer-created'
+  | 'world-updated'
+  | 'draw-submitted'
+  | 'validation-complete';
+
+export interface ToolPreviewTrace {
+  readonly events: readonly ToolPreviewTraceEvent[];
+  readonly backend: 'webgpu' | string;
+  readonly adapter: string;
+  readonly presentation: ToolPreviewPresentation;
+}
+
+export type ToolPreviewTraceValidation =
+  | { readonly ok: true; readonly value: ToolPreviewTrace }
+  | {
+      readonly ok: false;
+      readonly error: {
+        readonly code: 'tool-preview-invalid-trace';
+        readonly expected: string;
+        readonly hint: string;
+        readonly detail: { readonly missing: string; readonly index: number };
+      };
+    };
+
+export function createToolPreviewRecipe(options: ToolPreviewRecipeOptions): ToolPreviewRecipe {
+  if (options.backend !== undefined && options.backend !== 'webgpu') {
+    throw new TypeError('tool preview requires the real WebGPU backend');
+  }
+  const viewport = options.viewport ?? { width: 640, height: 360 };
+  if (
+    !Number.isSafeInteger(viewport.width) ||
+    !Number.isSafeInteger(viewport.height) ||
+    viewport.width <= 0 ||
+    viewport.height <= 0
+  ) {
+    throw new TypeError('tool preview viewport must contain positive safe integers');
+  }
+  const deltaSeconds = options.deltaSeconds ?? 1 / 60;
+  const frames = options.frames ?? 1;
+  if (!Number.isFinite(deltaSeconds) || deltaSeconds < 0) {
+    throw new TypeError('tool preview deltaSeconds must be finite and non-negative');
+  }
+  if (!Number.isSafeInteger(frames) || frames <= 0) {
+    throw new TypeError('tool preview frames must be a positive safe integer');
+  }
+  const actions = (options.actions ?? []).map((action) => ({ ...action }));
+  for (const action of actions) {
+    if (
+      !Number.isSafeInteger(action.frame) ||
+      action.frame < 0 ||
+      action.frame >= frames ||
+      action.name.length === 0 ||
+      (action.value !== undefined && !isSerializableValue(action.value))
+    ) {
+      throw new TypeError('tool preview actions require a valid frame, name, and JSON value');
+    }
+  }
+  return {
+    backend: 'webgpu',
+    presentation: options.presentation ?? 'hidden',
+    viewport: { width: viewport.width, height: viewport.height },
+    actions,
+    deltaSeconds,
+    frames,
+  };
+}
+
+const REQUIRED_EVENTS: readonly ToolPreviewTraceEvent[] = [
+  'canvas-created',
+  'rhi-debug-armed',
+  'renderer-created',
+  'world-updated',
+  'draw-submitted',
+  'validation-complete',
+];
+
+export function validateToolPreviewTrace(trace: ToolPreviewTrace): ToolPreviewTraceValidation {
+  if (trace.backend !== 'webgpu') {
+    return {
+      ok: false,
+      error: {
+        code: 'tool-preview-invalid-trace',
+        expected: 'trace.backend === "webgpu"',
+        hint: 'run the same recipe with a real WebGPU adapter; RHI-null is not a preview backend',
+        detail: { missing: 'webgpu-backend', index: -1 },
+      },
+    };
+  }
+  let last = -1;
+  for (const event of REQUIRED_EVENTS) {
+    const index = trace.events.indexOf(event);
+    if (index <= last) {
+      return {
+        ok: false,
+        error: {
+          code: 'tool-preview-invalid-trace',
+          expected: `event '${event}' occurs after the previous recipe phase`,
+          hint: 'arm RHI-debug before Renderer construction and retain update/draw/validation evidence',
+          detail: { missing: event, index },
+        },
+      };
+    }
+    last = index;
+  }
+  return { ok: true, value: trace };
+}