import { PrecompiledManifest } from 'three-blocks/shaders'; type ShaderBackend = 'webgpu' | 'webgl'; type ShaderBackendSelection = ShaderBackend | 'both'; interface ShaderSceneConfig { readonly key: string; /** Project-relative browser URL, including an optional query string. */ readonly url: string; /** Restrict this scene to one renderer backend. Absent means every configured backend. */ readonly backend?: ShaderBackend; readonly requiresText: boolean; /** Optional authoritative project-relative semantic inputs for this scene. */ readonly inputs?: readonly string[]; /** Optional scene-specific completed-frame count for deterministic parity. */ readonly parityFrames?: number; /** Optional scene-specific pixel-difference budget for intrinsically nondeterministic GPU work. */ readonly maxDiffRatio?: number; /** Require the normal published page's primary canvas to keep changing after startup. */ readonly runtimeMotion?: boolean; } interface ShaderParityConfig { readonly frames: number; readonly channelTolerance: number; readonly maxDiffRatio: number; } interface ShaderBridgeConfig { /** Temporary compatibility for the private integration lab's v1 globals. */ readonly legacyLab: boolean; /** Browser module exposing the lab's deterministic recording store. */ readonly deterministicModule?: string; } interface ShaderReadinessConfig { /** CSS selector whose presence marks the application ready for capture. */ readonly selector?: string; /** Dot-separated window/global property containing `true` or a readiness promise. */ readonly global?: string; } interface ShaderToolConfig { readonly schemaVersion: 1; /** Backends captured and release-gated by default. Absent means both. */ readonly backend?: ShaderBackendSelection; readonly scenes: readonly ShaderSceneConfig[]; readonly settleFrames: number; /** Total post-readiness settle ceiling. Defaults to 30 seconds. */ readonly settleTimeoutMs?: number; /** Chromium is relaunched after this many isolated capture contexts. Defaults to 8. */ readonly browserRelaunchScenes?: number; readonly timeoutMs: number; /** * Hard ceiling for one capture or parity observation when the page keeps * showing progress (new registered builds, advancing parity frames, or a * main thread busy compiling). `timeoutMs` remains the idle budget — a lane * with no progress still fails after `timeoutMs`. Defaults to `timeoutMs`, * which disables extension entirely. */ readonly maxTimeoutMs?: number; readonly viewport: { readonly width: number; readonly height: number; }; readonly parity: ShaderParityConfig; readonly bridge: ShaderBridgeConfig; readonly readiness: ShaderReadinessConfig; /** Static-asset root used for zero-import runtime manifests. Defaults to `public`. */ readonly publicDir?: string; /** Permit unregistered Three-internal/live builds in a receipt. Defaults true; set false for a strict matrix. */ readonly allowLiveBuilds: boolean; } declare function loadShaderToolConfig(root: string): Promise; type ArtifactState = 'fresh' | 'pending'; interface ProjectMetadataV2 { readonly schemaVersion: 2; /** Stable default shader scene key. It is not a template catalogue identity. */ readonly template: string; /** Informational project layers; devtools does not prescribe their catalogue or order. */ readonly layers: readonly string[]; readonly generator?: { readonly name: string; readonly version: string; }; readonly runtime: { readonly three: string; readonly threeBlocks: string; }; readonly features: { /** The only project capability currently consumed by the generic engine. */ readonly text: boolean; }; readonly artifacts?: { readonly shaders: ArtifactState; readonly text: ArtifactState | 'not-applicable'; }; readonly protocol: { readonly resultFile: 1; }; } interface ShaderCoverage { readonly render: number; readonly vertex: number; readonly fragment: number; readonly compute: number; } interface ShaderSceneReceipt { readonly backend?: 'webgpu' | 'webgl'; readonly artifact: string; readonly artifactHash: string; /** Path relative to the configured public directory. */ readonly asset?: string; readonly assetHash?: string; readonly inputs: Readonly>; readonly coverage: ShaderCoverage; readonly bytes?: number; readonly skipped?: { readonly render: number; readonly compute: number; }; } interface ShaderReceiptV2 { readonly schemaVersion: 2; readonly runtime: ProjectMetadataV2['runtime'] & { readonly threeBlocksShaderClosure: string; readonly capture?: { readonly userAgent: string; readonly adapter: string; readonly features: readonly string[]; }; }; readonly tool?: { readonly name: '@three-blocks/devtools'; readonly version: string; readonly compatibility: string; readonly compatibilities?: Partial>>; readonly transform: number; readonly address: number; readonly recipe: number; readonly hydration: number; }; readonly scenes: Readonly>; } /** Snapshot declared scene inputs, or discover shader roots and their local runtime import closure. */ declare function snapshotShaderInputs(root: string, declaredInputs?: readonly string[]): Promise>>; interface InstalledShaderRuntime { readonly three: string; readonly threeBlocks: string; readonly threeBlocksShaderClosure: string; } /** Read exact installed versions and hash the public `three-blocks/shaders` ESM closure. */ declare function readInstalledShaderRuntime(root: string): Promise; type ShaderMatrixState = 'fresh' | 'stale' | 'invalid' | 'missing'; interface ShaderSceneArtifactStatus { readonly scene: string; readonly backend: ShaderBackend; readonly state: ShaderMatrixState; readonly reason: string; readonly coverage?: ShaderCoverage; /** Build timing, exposed only while its exact receipt is fresh. */ readonly timing?: ShaderSceneTiming & { readonly schemaVersion: 3; readonly measuredAt: string; readonly source: ShaderTiming['source']; readonly adapter?: string; readonly platform?: string; }; readonly changedInputs?: readonly string[]; readonly addedInputs?: readonly string[]; readonly removedInputs?: readonly string[]; } interface ShaderMatrixStatus { readonly schemaVersion: 1; readonly root: string; readonly state: ShaderMatrixState; readonly reason: string; readonly scenes: readonly ShaderSceneArtifactStatus[]; readonly runtime?: InstalledShaderRuntime; readonly receipt?: ShaderReceiptV2; readonly timing?: ShaderTiming; } /** Inspect all configured manifests without launching Vite, a browser, or a GPU. */ declare function inspectShaderMatrix(start?: string, runtimeOverride?: InstalledShaderRuntime, backendOverride?: ShaderBackendSelection): Promise; declare const SHADER_PROVIDER_TRANSFORM_VERSION: 65; interface ShaderSceneTiming { /** Number of registered render/compute NodeBuilder builds covered by the manifest. */ readonly builds: number; /** True when the A/B measured and subtracted precompiled setup and hydration. */ readonly setupMeasured?: boolean; /** Cumulative NodeBuilder time observed while shaders build live. */ readonly liveBuildMs: number; /** Observed precompiled NodeBuilder setup/hydration time, or zero for a capture-only estimate. */ readonly precompiledBuildMs: number; /** Non-negative live minus precompiled NodeBuilder setup/hydration time. */ readonly avoidedBuildMs: number; /** One for a capture estimate; greater than one for warmed live/precompiled medians. */ readonly runs: number; /** Maximum absolute per-run deviation, or zero for a capture estimate. */ readonly spreadMs: number; } interface ShaderLocalTiming { readonly schemaVersion: 3; /** Binds this machine-local observation to the exact committed shader receipt. */ readonly receiptHash: string; readonly measuredAt: string; readonly source: 'latest-local-capture'; readonly scenes: Readonly>; } interface ShaderCommittedTiming { readonly schemaVersion: 3; readonly receiptHash: string; readonly measuredAt: string; readonly source: 'committed-capture'; readonly adapter: string; readonly platform: string; readonly scenes: Readonly>; } type ShaderTiming = ShaderLocalTiming | ShaderCommittedTiming; interface ShaderSkippedBuild { readonly kind: 'render' | 'compute'; readonly name: string; readonly reason: string; } interface ShaderCaptureStats { readonly buildCalls: number; readonly renderBuilds: number; readonly computeBuilds: number; readonly registeredBuilds: number; readonly registeredRenderBuilds: number; readonly registeredComputeBuilds: number; readonly buildMs: number; /** Synchronous `build()` time. */ readonly syncBuildMs?: number; /** `buildAsync()` wall time, including yielded time between stages. */ readonly asyncBuildElapsedMs?: number; /** Synchronous `prepareForHydration()` time retained by hydration. */ readonly precompiledSetupMs?: number; /** Longest synchronous `build()` call. */ readonly maxSyncBuildMs?: number; /** Longest synchronous `prepareForHydration()` call. */ readonly maxPrecompiledSetupMs?: number; /** Total synchronous declaration/binding replay time. */ readonly hydrationMs?: number; /** Longest synchronous declaration/binding replay call. */ readonly maxHydrationMs?: number; readonly injected: number; readonly injectedRender: number; readonly injectedCompute: number; readonly missed: number; readonly missedRender: number; readonly missedCompute: number; /** Stable registered shader keys that fell back to a live build. */ readonly missedKeys?: readonly string[]; /** Verdict of a state-oracle observation; absent on every other lane. */ readonly stateOracle?: ShaderStateOracleStats; } /** Hydrated states compared with a live build of the same key in the same page. */ interface ShaderStateOracleStats { readonly checked: number; readonly equivalent: number; /** Application nodes bound by both the hydrated state and the live build. */ readonly identical: number; /** Application node recreated by hydration over the same value object. */ readonly recreated: number; readonly differences: readonly string[]; } interface ShaderCaptureStageTiming { readonly launch?: number; readonly firstRequest?: number; readonly readiness?: number; readonly lastBuild?: number; readonly settled?: number; readonly posted?: number; } interface ShaderCaptureProvenance { readonly userAgent: string; readonly adapter: string; readonly features: readonly string[]; } interface ValidatedShaderCapture { readonly scene: string; readonly backend: ShaderBackend; readonly manifest: PrecompiledManifest; readonly skipped: readonly ShaderSkippedBuild[]; readonly stats: ShaderCaptureStats; readonly coverage: ShaderCoverage; readonly timing?: ShaderCaptureStageTiming; readonly provenance?: ShaderCaptureProvenance; } interface ValidateShaderCaptureOptions { readonly scene: string; readonly backend?: ShaderBackend; readonly runtime: InstalledShaderRuntime; } /** Validate untrusted browser capture data through the public runtime manifest schema. */ declare function validateShaderCapture(value: unknown, options: ValidateShaderCaptureOptions): ValidatedShaderCapture; declare function stableStringify(value: unknown, indent?: number): string; interface WriteShaderArtifactsOptions { readonly root: string; readonly scenes: readonly ShaderSceneConfig[]; readonly backends?: readonly ShaderBackend[]; readonly captures: ReadonlyMap; readonly runtime: InstalledShaderRuntime; readonly inputs: ReadonlyMap>>; readonly previousReceipt?: ShaderReceiptV2; readonly publicDirectory?: string; } interface WrittenShaderArtifacts { readonly directory: string; readonly receipt: ShaderReceiptV2; readonly files: readonly string[]; } /** Write a complete deterministic scene matrix, with meta.json committed last. */ declare function writeShaderArtifacts(options: WriteShaderArtifactsOptions): Promise; declare function loadShaderCaptureRuntimeSource(): Promise; export { type InstalledShaderRuntime, SHADER_PROVIDER_TRANSFORM_VERSION, type ShaderMatrixStatus, type ValidatedShaderCapture, inspectShaderMatrix, loadShaderCaptureRuntimeSource, loadShaderToolConfig, readInstalledShaderRuntime, snapshotShaderInputs, stableStringify, validateShaderCapture, writeShaderArtifacts };