@forgeax/engine-preview 0.1.2

package/dist/domains/texture.d.ts

@@ -0,0 +1,63 @@
+import type { ArtifactRef } from '@forgeax/engine-tool-runtime';
+import { type TextureOracleInput } from '../evidence/oracle.js';
+import type { PreviewAssetRegistry, PreviewRenderRuntime } from '../host/preview-host.js';
+import { type ResourcePreviewArgs, subjectFailure } from './subject.js';
+export interface TextureSubjectInspection {
+    readonly subjectDigest: string;
+    readonly boundDigest: string;
+    readonly dimensions: readonly [number, number];
+    readonly format: string;
+    readonly colorSpace: string;
+    readonly mipCount: number;
+    readonly uvDigest: string;
+    readonly filter: string;
+    readonly bindingDigest: string;
+    readonly payloadClass: TextureOracleInput['observed']['payloadClass'];
+}
+type InspectionResult = {
+    readonly ok: true;
+    readonly value: TextureSubjectInspection;
+} | ReturnType<typeof subjectFailure>;
+export declare function inspectTextureSubject(input: {
+    readonly guid: string;
+    readonly asset: unknown;
+    readonly digest?: string;
+    readonly ownerFacts?: Readonly<Record<string, string | number | boolean>>;
+}): InspectionResult;
+export declare function executeTexturePreview(args: ResourcePreviewArgs, input: {
+    readonly assets?: PreviewAssetRegistry;
+    readonly renderer?: PreviewRenderRuntime;
+    readonly runId: string;
+    readonly artifacts?: readonly ArtifactRef[];
+}): Promise<import("./subject.js").ResourceSubjectFailure | {
+    ok: true;
+    value: {
+        subject: {
+            kind: "texture";
+            guid: string;
+            digest: string;
+        };
+        presentation: import("../index.js").PreviewPresentation;
+        recipe: import("../index.js").CanonicalPreviewRecipe;
+        quad: {
+            projection: string;
+            aspect: string;
+            stage: string;
+        };
+        binding: {
+            filter: string;
+            digest: string;
+        };
+        oracle: {
+            readonly status: "passed";
+            readonly subjectBound: true;
+            readonly drawCalls: number;
+            readonly dispatches: number;
+            readonly rendererHealthy: true;
+            readonly detail: Record<string, string | number | boolean>;
+        };
+        artifacts: readonly ArtifactRef[];
+    };
+    artifacts: readonly ArtifactRef[];
+}>;
+export {};

package/dist/domains/vfx.d.ts

@@ -0,0 +1,58 @@
+import type { ArtifactRef } from '@forgeax/engine-tool-runtime';
+import type { PreviewAssetRegistry, PreviewRenderRuntime } from '../host/preview-host.js';
+import { type ResourcePreviewArgs, subjectFailure } from './subject.js';
+export interface VfxSubjectInspection {
+    readonly subjectDigest: string;
+    readonly programFingerprint: string;
+    readonly emitterDigest: string;
+    readonly sampleDigest: string;
+    readonly boundsDigest: string;
+    readonly computeDigest: string;
+    readonly indirectDigest: string;
+    readonly contactSheetDigest?: string;
+    readonly authoredBounds: readonly [number, number, number, number, number, number];
+}
+type InspectionResult = {
+    readonly ok: true;
+    readonly value: VfxSubjectInspection;
+} | ReturnType<typeof subjectFailure>;
+export declare function inspectVfxSubject(input: {
+    readonly guid: string;
+    readonly asset: unknown;
+    readonly digest?: string;
+    readonly ownerFacts?: Readonly<Record<string, string | number | boolean>>;
+}): InspectionResult;
+export declare function executeVfxPreview(args: ResourcePreviewArgs, input: {
+    readonly assets?: PreviewAssetRegistry;
+    readonly renderer?: PreviewRenderRuntime;
+    readonly runId: string;
+    readonly artifacts?: readonly ArtifactRef[];
+}): Promise<import("./subject.js").ResourceSubjectFailure | {
+    ok: true;
+    value: {
+        subject: {
+            kind: "vfx";
+            guid: string;
+            digest: string;
+        };
+        presentation: import("../index.js").PreviewPresentation;
+        recipe: import("../index.js").CanonicalPreviewRecipe;
+        authoredBounds: readonly [number, number, number, number, number, number];
+        timeline: {
+            seed: number;
+            fixedDelta: number;
+            frames: number;
+        };
+        oracle: {
+            readonly status: "passed";
+            readonly subjectBound: true;
+            readonly drawCalls: number;
+            readonly dispatches: number;
+            readonly rendererHealthy: true;
+            readonly detail: Record<string, string | number | boolean>;
+        };
+        artifacts: readonly ArtifactRef[];
+    };
+    artifacts: readonly ArtifactRef[];
+}>;
+export {};

package/dist/evidence/errors.d.ts

@@ -0,0 +1,14 @@
+import type { JsonValue, ToolRecoveryAction, ToolRuntimeError } from '@forgeax/engine-tool-runtime';
+export type ResourcePreviewFailureCode = 'resource-preview-kind-mismatch' | 'resource-preview-subject-invalid' | 'resource-preview-oracle-failed';
+export interface ResourcePreviewFailure {
+    readonly code: ResourcePreviewFailureCode;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: Readonly<Record<string, JsonValue>>;
+}
+export interface ResourcePreviewRecovery {
+    readonly failure: ResourcePreviewFailure;
+    readonly suggestedOperation?: string;
+    readonly actions: readonly ToolRecoveryAction[];
+}
+export declare function describeResourcePreviewFailure(failure: ToolRuntimeError): ResourcePreviewRecovery | undefined;

package/dist/evidence/manifest.d.ts

@@ -0,0 +1,10 @@
+import { type PreviewArtifactManifest, type PreviewArtifactManifestValidation, type PreviewArtifactRole } from '@forgeax/engine-tool-runtime';
+export { createPreviewArtifactManifest, type PreviewArtifactIdentity, type PreviewArtifactKind, type PreviewArtifactManifest, type PreviewArtifactManifestEntry, type PreviewArtifactManifestValidation, type PreviewArtifactRole, validatePreviewArtifactManifest, } from '@forgeax/engine-tool-runtime';
+export interface AtomicPreviewPublisher {
+    readonly stage: (manifest: PreviewArtifactManifest) => void;
+    readonly publish: (requiredRoles: readonly PreviewArtifactRole[]) => PreviewArtifactManifestValidation;
+    readonly discard: () => void;
+    readonly published: () => PreviewArtifactManifest | undefined;
+}
+/** In-memory atomic boundary shared by Browser, Dawn, and visible carriers. */
+export declare function createAtomicPreviewPublisher(): AtomicPreviewPublisher;

package/dist/evidence/oracle.d.ts

@@ -0,0 +1,104 @@
+export type PreviewOracleStatus = PreviewOracle['status'];
+export type PreviewOracle = {
+    readonly status: 'passed';
+    readonly subjectBound: true;
+    readonly drawCalls: number;
+    readonly dispatches: number;
+    readonly rendererHealthy: true;
+    readonly detail: Record<string, string | number | boolean>;
+} | {
+    readonly status: 'failed';
+    readonly subjectBound: false;
+    readonly drawCalls: number;
+    readonly dispatches: number;
+    readonly rendererHealthy: boolean;
+    readonly detail: Record<string, string | number | boolean>;
+};
+export declare function passedPreviewOracle(input: {
+    readonly drawCalls: number;
+    readonly dispatches?: number;
+    readonly detail: Record<string, string | number | boolean>;
+}): PreviewOracle;
+export declare function failedPreviewOracle(input: {
+    readonly drawCalls?: number;
+    readonly dispatches?: number;
+    readonly rendererHealthy?: boolean;
+    readonly detail: Record<string, string | number | boolean>;
+}): PreviewOracle;
+export interface MaterialOracleInput {
+    readonly requested: {
+        readonly subjectDigest: string;
+        readonly program: string;
+        readonly pass: string;
+        readonly bindingsDigest: string;
+        readonly closureDigest: string;
+    };
+    readonly observed: MaterialOracleInput['requested'] & {
+        readonly rendererHealthy: boolean;
+        readonly drawCalls: number;
+        readonly nonBlackPixels: number;
+    };
+}
+export interface MeshOracleInput {
+    readonly requested: {
+        readonly subjectDigest: string;
+        readonly vertexDigest: string;
+        readonly indexDigest: string;
+        readonly submeshDigest: string;
+        readonly aabbDigest: string;
+        readonly aabb?: readonly [number, number, number, number, number, number];
+        readonly submeshCount?: number;
+        readonly materialSlotCount?: number;
+    };
+    readonly observed: MeshOracleInput['requested'] & {
+        readonly rendererHealthy: boolean;
+        readonly drawCalls: number;
+        readonly nonBlackPixels: number;
+    };
+}
+export declare function evaluateMaterialOracle(input: MaterialOracleInput): PreviewOracle;
+export declare function evaluateMeshOracle(input: MeshOracleInput): PreviewOracle;
+export interface VfxOracleInput {
+    readonly requested: {
+        readonly subjectDigest: string;
+        readonly programFingerprint: string;
+        readonly emitterDigest: string;
+        readonly sampleDigest: string;
+        readonly boundsDigest: string;
+        readonly computeDigest: string;
+        readonly indirectDigest: string;
+        readonly contactSheetDigest?: string;
+        readonly authoredBounds?: readonly [number, number, number, number, number, number];
+        readonly seed?: number;
+        readonly fixedDelta?: number;
+        readonly timelineFrames?: number;
+    };
+    readonly observed: VfxOracleInput['requested'] & {
+        readonly rendererHealthy: boolean;
+        readonly dispatches: number;
+        readonly indirectDraws: number;
+        readonly subjectOutputs: number;
+        readonly nonBlackPixels: number;
+    };
+}
+export interface TextureOracleInput {
+    readonly requested: {
+        readonly subjectDigest: string;
+        readonly boundDigest: string;
+        readonly dimensions: readonly [number, number];
+        readonly format: string;
+        readonly colorSpace: string;
+        readonly mipCount: number;
+        readonly uvDigest: string;
+        readonly filter: string;
+        readonly bindingDigest: string;
+    };
+    readonly observed: TextureOracleInput['requested'] & {
+        readonly rendererHealthy: boolean;
+        readonly drawCalls: number;
+        readonly nonBlackPixels: number;
+        readonly payloadClass: 'black' | 'transparent' | 'single-channel' | 'color';
+    };
+}
+export declare function evaluateVfxOracle(input: VfxOracleInput): PreviewOracle;
+export declare function evaluateTextureOracle(input: TextureOracleInput): PreviewOracle;

package/dist/evidence/report.d.ts

@@ -0,0 +1,15 @@
+import type { SnapshotRef } from '@forgeax/engine-tool-runtime';
+import type { PreviewPresentation, PreviewSubject } from '../kit/presentation.js';
+import type { PreviewArtifactManifestEntry } from './manifest.js';
+import type { PreviewOracle } from './oracle.js';
+export interface ResourcePreviewReport {
+    readonly mediaType: 'application/vnd.forgeax.resource-preview+json';
+    readonly schemaVersion: '1.0.0';
+    readonly runId: string;
+    readonly snapshot: SnapshotRef;
+    readonly subject: PreviewSubject;
+    readonly presentation: PreviewPresentation;
+    readonly oracle: PreviewOracle;
+    readonly artifacts: readonly PreviewArtifactManifestEntry[];
+}
+export declare function createResourcePreviewReport(input: Omit<ResourcePreviewReport, 'mediaType' | 'schemaVersion'>): ResourcePreviewReport;

package/dist/host/preview-host.d.ts

@@ -0,0 +1,52 @@
+import { type Plugin, type ToolPlugin } from '@forgeax/engine-plugin';
+import { type ArtifactRef, type SnapshotRef } from '@forgeax/engine-tool-runtime';
+import type { AssetKind } from '@forgeax/engine-types';
+export interface PreviewAssetLoadResult<TAsset = unknown> {
+    readonly ok: true;
+    readonly value: TAsset;
+    readonly digest?: string;
+    readonly ownerFacts?: Readonly<Record<string, string | number | boolean>>;
+}
+export interface PreviewAssetLoadFailure {
+    readonly ok: false;
+    readonly error: unknown;
+}
+export interface PreviewAssetRegistry {
+    readonly load: <TAsset, TKind extends string>(guid: string, kind: AssetKind<TAsset, TKind>) => Promise<PreviewAssetLoadResult<TAsset> | PreviewAssetLoadFailure>;
+}
+export interface PreviewRenderRuntime {
+    readonly rendererReady: boolean;
+    readonly worldReady: boolean;
+    readonly drawCalls: number;
+    readonly nonBlackPixels: number;
+    /**
+     * Facts read back from the real render/asset owner path. Domain executors
+     * must not manufacture observed identity from the requested subject.
+     */
+    readonly observation?: Readonly<Record<string, string | number | boolean | readonly number[]>>;
+    readonly vfx?: {
+        readonly dispatches: number;
+        readonly indirectDraws: number;
+        readonly subjectOutputs: number;
+    };
+    readonly texture?: {
+        readonly drawCalls: number;
+    };
+}
+export interface PreviewHostMechanisms {
+    readonly runId: string;
+    readonly snapshot: SnapshotRef;
+    readonly projectRoot: string;
+    readonly backend: 'webgpu';
+    readonly signal: AbortSignal;
+    readonly assets?: PreviewAssetRegistry;
+    readonly renderer?: PreviewRenderRuntime;
+    readonly artifacts?: readonly ArtifactRef[];
+}
+export interface PreviewHost {
+    readonly withSession: <T>(execute: (mechanisms: PreviewHostMechanisms) => Promise<T>) => Promise<T>;
+}
+export declare const previewHostCapability: import("@forgeax/engine-tool-runtime").ToolCapability<PreviewHost>;
+export declare function previewHostPlugin(host: PreviewHost): Plugin;
+export declare function bindPreviewHost(plugin: ToolPlugin, host: PreviewHost): ToolPlugin;
+export declare function createPreviewHost(input: PreviewHostMechanisms): PreviewHost;

package/dist/host.d.ts

@@ -0,0 +1,88 @@
+import type { ArtifactRef, JsonValue, SnapshotRef, ToolDomainFailure, ToolEvidenceKind, ToolExecutionContext, ToolSubjectRef } from '@forgeax/engine-tool-runtime';
+import { type PreviewHost as NativePreviewHost, type PreviewHostMechanisms } from './host/preview-host.js';
+export interface PreviewHostRequest {
+    readonly subject: ToolSubjectRef;
+    readonly snapshot: SnapshotRef;
+}
+export interface PreviewAssetBinding {
+    readonly guid: string;
+    readonly bytes: number;
+}
+export interface PreviewFrameInput {
+    readonly frame: number;
+    readonly deltaSeconds: number;
+}
+export interface PreviewCapture {
+    readonly digest: string;
+    readonly bytes: number;
+}
+export interface PreviewResourceCensus {
+    readonly worlds: number;
+    readonly renderers: number;
+    readonly canvases: number;
+    readonly leases: number;
+}
+export interface PreviewCleanupReport {
+    readonly census: PreviewResourceCensus;
+    readonly failures: readonly string[];
+}
+/**
+ * The only resource surface exposed to a preview contribution. The adapter owns
+ * the actual Engine resources; callers receive POD bindings and bounded actions.
+ */
+export interface PreviewHostSession {
+    readonly subject: ToolSubjectRef;
+    readonly snapshot: SnapshotRef;
+    readonly loadAsset: (guid: string) => Promise<PreviewAssetBinding>;
+    readonly frame: (input: PreviewFrameInput) => Promise<void>;
+    readonly capture: () => Promise<PreviewCapture & {
+        readonly artifact?: ArtifactRef;
+    }>;
+    readonly census: () => PreviewResourceCensus;
+    readonly dispose: () => Promise<void>;
+}
+export interface PreviewHostAdapter {
+    readonly open: (request: PreviewHostRequest) => PreviewHostSession | Promise<PreviewHostSession>;
+}
+export interface PreviewHost {
+    readonly withSession: <TResult>(request: PreviewHostRequest, run: (session: PreviewHostSession) => TResult | Promise<TResult>) => Promise<{
+        readonly value: TResult;
+        readonly cleanup: PreviewCleanupReport;
+    }>;
+}
+export interface PreviewDomainValue<TReport = unknown> {
+    readonly subject: ToolSubjectRef;
+    readonly snapshot: SnapshotRef;
+    readonly report: TReport;
+    readonly artifacts: readonly ArtifactRef[];
+}
+export type PreviewDomainResult<TReport = unknown> = {
+    readonly ok: true;
+    readonly value: PreviewDomainValue<TReport>;
+} | {
+    readonly ok: false;
+    readonly error: ToolDomainFailure;
+};
+export type PreviewDomainRunner<TRequest, TReport = unknown> = (request: TRequest, context: ToolExecutionContext) => Promise<PreviewDomainResult<TReport>>;
+export declare const REQUIRED_PREVIEW_EVIDENCE: readonly ToolEvidenceKind[];
+export declare function domainFailure(code: string, expected: string, hint: string, detail: Record<string, JsonValue>): {
+    readonly ok: false;
+    readonly error: ToolDomainFailure;
+};
+/**
+ * The default contribution is deliberately fail-closed. A real Project GUID
+ * loader must install a PreviewHost/Browser/Dawn runner; a data-only request
+ * must never manufacture PNG, RHI, or profile references from its arguments.
+ */
+export declare function previewRuntimeUnavailable(subject: ToolSubjectRef, snapshot: SnapshotRef, domain: string): {
+    readonly ok: false;
+    readonly error: ToolDomainFailure;
+};
+export declare function validateDomainValue<TReport>(value: PreviewDomainValue<TReport>, request: PreviewHostRequest): PreviewDomainResult<TReport>;
+export declare class PreviewCleanupError extends Error {
+    readonly code = "preview-cleanup-live-resources";
+    readonly census: PreviewResourceCensus;
+    constructor(census: PreviewResourceCensus, failures?: readonly string[]);
+}
+export declare function createPreviewHost(adapter: PreviewHostAdapter): PreviewHost;
+export declare function createPreviewHost(input: PreviewHostMechanisms): NativePreviewHost;

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { isResourcePreviewSize, RESOURCE_PREVIEW_DEFAULT_SIZE, RESOURCE_PREVIEW_MAX_SIZE, RESOURCE_PREVIEW_MIN_SIZE, type ResourcePreviewArgs, } from './domains/subject.js';
+export { describeResourcePreviewFailure, type ResourcePreviewFailure, type ResourcePreviewFailureCode, type ResourcePreviewRecovery, } from './evidence/errors.js';
+export { type AtomicPreviewPublisher, createAtomicPreviewPublisher, createPreviewArtifactManifest, type PreviewArtifactIdentity, type PreviewArtifactKind, type PreviewArtifactManifest, type PreviewArtifactManifestEntry, type PreviewArtifactManifestValidation, type PreviewArtifactRole, validatePreviewArtifactManifest, } from './evidence/manifest.js';
+export { evaluateMaterialOracle, evaluateMeshOracle, evaluateTextureOracle, evaluateVfxOracle, failedPreviewOracle, type MaterialOracleInput, type MeshOracleInput, type PreviewOracle, type PreviewOracleStatus, passedPreviewOracle, type TextureOracleInput, type VfxOracleInput, } from './evidence/oracle.js';
+export { createResourcePreviewReport, type ResourcePreviewReport } from './evidence/report.js';
+export { bindPreviewHost, createPreviewHost as createNativePreviewHost, type PreviewAssetLoadFailure, type PreviewAssetLoadResult, type PreviewAssetRegistry, type PreviewHost as NativePreviewHost, type PreviewHostMechanisms, type PreviewRenderRuntime, previewHostCapability, previewHostPlugin, } from './host/preview-host.js';
+export { createPreviewHost, type PreviewAssetBinding, type PreviewCapture, PreviewCleanupError, type PreviewCleanupReport, type PreviewFrameInput, type PreviewHost, type PreviewHostAdapter, type PreviewHostRequest, type PreviewHostSession, type PreviewResourceCensus, previewRuntimeUnavailable, } from './host.js';
+export { type CanonicalPreviewRecipe, canonicalPresentation, createCanonicalPreviewRecipe, } from './kit/canonical.js';
+export { MATERIAL_PRESENTATION, MESH_PRESENTATION, type PreviewPresentation, type PreviewSubject, type PreviewSubjectKind, TEXTURE_PRESENTATION, VFX_PRESENTATION, } from './kit/presentation.js';
+export { type CanonicalKitReceipt, type CanonicalKitReceiptValidation, validateCanonicalKitReceipt, } from './kit/receipt.js';
+export { createMaterialPreviewContribution, type MaterialBinding, type MaterialPreviewReport, type MaterialPreviewRequest, materialPreviewDescriptor, } from './material.js';
+export { createMeshPreviewContribution, type MeshAabb, type MeshBinding, type MeshPreviewReport, type MeshPreviewRequest, type MeshSubmeshBinding, meshPreviewDescriptor, } from './mesh.js';
+export { createMaterialPreviewPrimitive, createMeshPreviewPrimitive, createTexturePreviewPrimitive, createVfxPreviewPrimitive, type MaterialPreviewPrimitive, type MeshPreviewPrimitive, materialBindingFromPayload, meshBindingFromPayload, type PreviewSnapshot, previewSnapshot, type TexturePreviewPrimitive, type VfxPreviewPrimitive, } from './primitive.js';
+export { createTexturePreviewContribution, type TextureBinding, type TextureColorSpace, type TexturePreviewReport, type TexturePreviewRequest, texturePreviewDescriptor, } from './texture.js';
+export { createVfxPreviewContribution, type VfxBinding, type VfxPreviewReport, type VfxPreviewRequest, type VfxSimulationInput, vfxDeterministicDigest, vfxPreviewDescriptor, } from './vfx.js';