@three-blocks/devtools 1.0.0-alpha.176.g8ff8a72e6369

package/dist/index.d.ts

@@ -0,0 +1,1183 @@
+import { PrecompiledManifest } from 'three-blocks/shaders';
+export { A as AppliedShaderProviderTransform, a as ApplyShaderProviderTransformOptions, S as SHADER_CAPTURE_CLIENT_ID, b as ShaderCaptureTransformOptions, c as ShaderProviderTransform, d as ShaderProviderTransformOptions, e as ShaderProviderTransformStatus, f as applyShaderProviderTransform, g as assertShaderProviderTransform, h as createShaderProviderTransform } from './shader-transform-CUkZn5Oa.js';
+import 'vite';
+
+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;
+    };
+}
+declare function parseProjectMetadata(value: unknown): ProjectMetadataV2;
+interface ShaderCoverage {
+    readonly render: number;
+    readonly vertex: number;
+    readonly fragment: number;
+    readonly compute: number;
+}
+interface ShaderSceneReceipt {
+    readonly artifact: string;
+    readonly artifactHash: string;
+    /** Path relative to the configured public directory. */
+    readonly asset?: string;
+    readonly assetHash?: string;
+    readonly inputs: Readonly<Record<string, string>>;
+    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 transform: number;
+        readonly address: number;
+        readonly recipe: number;
+        readonly hydration: number;
+    };
+    readonly scenes: Readonly<Record<string, ShaderSceneReceipt>>;
+}
+declare function parseShaderReceipt(value: unknown): ShaderReceiptV2;
+
+declare const TEXT_ATLAS_SCHEMA_VERSION = 1;
+declare const TEXT_ATLAS_GENERATOR_VERSION = "1.0.0";
+interface BuiltinFontMetadata {
+    readonly id: string;
+    readonly family: string;
+    readonly version: string;
+    readonly license: 'OFL-1.1';
+    readonly licenseFile: string;
+    readonly sourceFile: string;
+    readonly sourceUrl: string;
+    readonly sourceBytes: number;
+    readonly sourceChecksum: string;
+    readonly sourceArchive?: {
+        readonly bytes: number;
+        readonly checksum: string;
+        readonly entry: string;
+    };
+    readonly browserFile: string;
+    readonly browserUrl: string;
+    readonly browserBytes: number;
+    readonly browserChecksum: string;
+}
+type FetchFontAsset = (input: string | URL | globalThis.Request, init?: globalThis.RequestInit) => Promise<globalThis.Response>;
+interface TextAtlasRuntimeOptions {
+    /** Override the platform user cache. Primarily useful for CI and cache prewarming. */
+    readonly cacheDirectory?: string;
+    /** Override network transport without changing the immutable source metadata. */
+    readonly fetch?: FetchFontAsset;
+    /** Override download location/archive metadata while retaining the pinned extracted-file checksums. */
+    readonly mapBuiltinFont?: (metadata: BuiltinFontMetadata) => BuiltinFontMetadata;
+}
+interface AtlasOptions {
+    readonly size: number;
+    readonly distanceRange: number;
+    readonly padding: number;
+    readonly maxTextureSize: number;
+}
+interface TextAtlasFileReceipt {
+    readonly path: string;
+    readonly sha256: string;
+    readonly bytes: number;
+}
+interface TextAtlasGenerationReceipt {
+    readonly schemaVersion: typeof TEXT_ATLAS_SCHEMA_VERSION;
+    readonly generatorVersion: typeof TEXT_ATLAS_GENERATOR_VERSION;
+    readonly font: {
+        readonly key: string;
+        readonly source: string;
+        readonly sourceHash: string;
+        readonly license?: BuiltinFontMetadata['license'];
+    };
+    readonly inputHash: string;
+    readonly glyphSetHash: string;
+    readonly codePoints: readonly number[];
+    readonly options: AtlasOptions;
+    readonly texture: {
+        readonly format: 'RGBA8';
+        readonly orientation: 'rd';
+        readonly compression: 'zstd' | 'none';
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly files: {
+        readonly browser: TextAtlasFileReceipt;
+        readonly atlas: TextAtlasFileReceipt;
+        readonly metrics: TextAtlasFileReceipt;
+    };
+}
+interface GeneratedTextAtlas {
+    readonly font: string;
+    readonly receipt: TextAtlasGenerationReceipt;
+    readonly metadataPath: string;
+    readonly updatedFiles: readonly string[];
+}
+interface GenerateTextResult {
+    readonly glyphs: number;
+    readonly glyphSetHash: string;
+    readonly atlases: readonly GeneratedTextAtlas[];
+    readonly updatedFiles: readonly string[];
+}
+interface TextAtlasInspection {
+    readonly state: 'ready' | 'missing' | 'invalid';
+    readonly reason: string;
+    readonly missing: readonly number[];
+    readonly atlases: readonly TextAtlasGenerationReceipt[];
+}
+declare function builtinFontMetadata(id: string): BuiltinFontMetadata;
+/** Download and verify one built-in font pair without generating an atlas. */
+declare function prewarmBuiltinFont(id: string, options?: TextAtlasRuntimeOptions): Promise<void>;
+/** Generate every configured atlas only from semantically declared text content. */
+declare function generateTextAtlases(root: string, configurationPath?: string, runtimeOptions?: TextAtlasRuntimeOptions): Promise<GenerateTextResult>;
+declare function parseTextAtlasReceipt(value: unknown): TextAtlasGenerationReceipt;
+/** Validate text coverage, metadata, KTX2 decoding, dimensions, orientation, and freshness without a GPU. */
+declare function inspectTextAtlases(root: string, configurationPath?: string): Promise<TextAtlasInspection>;
+
+declare const SHADER_TOOL_CONFIG_FILE = "three-blocks.shaders.json";
+declare const SHADER_ARTIFACT_DIRECTORY = ".three-blocks/shaders";
+declare const SHADER_PARITY_DIRECTORY = ".three-blocks/shaders/parity";
+interface ShaderSceneConfig {
+    readonly key: string;
+    /** Project-relative browser URL, including an optional query string. */
+    readonly url: string;
+    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;
+    /** Permit Three's backend pipeline cache to reuse an earlier injected pipeline with identical WGSL. */
+    readonly allowPipelineReuse?: boolean;
+    /** 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;
+    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;
+    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 parseShaderToolConfig(value: unknown): ShaderToolConfig;
+declare function findShaderProjectRoot(start?: string): Promise<string>;
+declare function loadShaderToolConfig(root: string): Promise<ShaderToolConfig>;
+interface EnsuredShaderToolConfig {
+    readonly config: ShaderToolConfig;
+    readonly file: string;
+    readonly created: boolean;
+}
+interface InferredShaderCaptureTarget {
+    readonly driverKind: 'vite' | 'static';
+    readonly serve?: string;
+    readonly reason: string;
+}
+/** Select the zero-flag browser driver from the target project's own build shape. */
+declare function inferShaderCaptureTarget(root: string): Promise<InferredShaderCaptureTarget>;
+/**
+ * Materialize the convention single-scene configuration on first capture.
+ * Existing explicit configuration and generated-project metadata remain authoritative.
+ */
+declare function ensureShaderToolConfig(root: string): Promise<EnsuredShaderToolConfig>;
+
+/** Published devtools protocol/package version. Kept dependency-free for instant CLI startup. */
+declare const SHADER_DEVTOOLS_VERSION: "0.1.0";
+
+declare const SHADER_PROVIDER_TRANSFORM_VERSION: 3;
+declare const SHADER_LOCAL_TIMING_FILE: "timing.local.json";
+declare const SHADER_COMMITTED_TIMING_FILE: "timing.json";
+declare const SHADER_PARITY_EVIDENCE_FILE: "parity.json";
+interface ShaderSceneTiming {
+    /** Number of registered render/compute NodeBuilder builds covered by the manifest. */
+    readonly builds: number;
+    /** Cumulative NodeBuilder time in the live half of the capture. */
+    readonly liveBuildMs: number;
+    /** Cumulative NodeBuilder time in the precompiled half of the same capture. */
+    readonly precompiledBuildMs: number;
+    /** Non-negative live minus precompiled NodeBuilder time. */
+    readonly avoidedBuildMs: number;
+    /** Number of measured live/precompiled pairs represented by the medians. */
+    readonly runs: number;
+    /** Maximum absolute per-run saved-time deviation from the median. */
+    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<Record<string, ShaderSceneTiming>>;
+}
+interface ShaderCommittedTiming {
+    readonly schemaVersion: 3;
+    readonly receiptHash: string;
+    readonly measuredAt: string;
+    readonly source: 'committed-capture';
+    readonly adapter: string;
+    readonly platform: string;
+    readonly scenes: Readonly<Record<string, ShaderSceneTiming>>;
+}
+type ShaderTiming = ShaderLocalTiming | ShaderCommittedTiming;
+interface ShaderTimingEnvironment {
+    readonly adapter: string;
+    readonly platform: string;
+}
+interface ShaderSceneParityEvidence {
+    /** Binds one successful browser comparison to its scene plus shared runtime/tool receipt inputs. */
+    readonly fingerprint: string;
+    readonly verifiedAt: string;
+}
+interface ShaderParityEvidence {
+    readonly schemaVersion: 2;
+    readonly scenes: Readonly<Record<string, ShaderSceneParityEvidence>>;
+}
+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;
+    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[];
+}
+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 ShaderCapturePayload extends Pick<PrecompiledManifest, 'modules' | 'nodes' | 'layouts' | 'attributePlans' | 'updatePlans' | 'requirementPlans' | 'states' | 'entries'> {
+    readonly protocolVersion: 2;
+    readonly compatibility: string;
+    readonly scene: string;
+    readonly automatic?: {
+        readonly prefix: string;
+    };
+    readonly skipped: readonly ShaderSkippedBuild[];
+    readonly errors: readonly string[];
+    readonly stats: ShaderCaptureStats;
+    readonly timing?: ShaderCaptureStageTiming;
+    readonly provenance?: ShaderCaptureProvenance;
+}
+interface ValidatedShaderCapture {
+    readonly scene: string;
+    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 runtime: InstalledShaderRuntime;
+}
+declare function shaderCoverage(manifest: PrecompiledManifest): ShaderCoverage;
+/** 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;
+declare function serializeShaderManifest(manifest: PrecompiledManifest): string;
+/** Read machine-local timing only when it matches the exact receipt bytes. */
+declare function readShaderLocalTiming(directory: string, receipt: Uint8Array): Promise<ShaderLocalTiming | undefined>;
+/** Read exact timing twins, preferring the machine-local observation. */
+declare function readShaderTiming(directory: string, receipt: Uint8Array): Promise<ShaderTiming | undefined>;
+/** Read browser parity evidence for the scenes that still match the current receipt. */
+declare function readShaderParityEvidence(directory: string, receipt: Uint8Array): Promise<ShaderParityEvidence | undefined>;
+/** Read only the canonical, committed timing file for an exact receipt. */
+declare function readShaderCommittedTiming(directory: string, receipt: Uint8Array): Promise<ShaderCommittedTiming | undefined>;
+/** Persist successful build timing, bound to the exact current shader receipt. */
+declare function writeShaderLocalTiming(root: string, scenes: Readonly<Record<string, ShaderSceneTiming>>): Promise<ShaderLocalTiming>;
+/** Persist successful browser parity checkpoints for exact per-scene receipt inputs. */
+declare function writeShaderParityEvidence(root: string, scenes: readonly string[], expectedReceipt?: Uint8Array): Promise<ShaderParityEvidence>;
+/** Persist local timing and its explicitly requested committed twin. */
+declare function writeShaderTimingTwins(root: string, scenes: Readonly<Record<string, ShaderSceneTiming>>, environment: ShaderTimingEnvironment): Promise<{
+    readonly local: ShaderLocalTiming;
+    readonly committed: ShaderCommittedTiming;
+}>;
+interface WriteShaderArtifactsOptions {
+    readonly root: string;
+    readonly scenes: readonly ShaderSceneConfig[];
+    readonly captures: ReadonlyMap<string, ValidatedShaderCapture>;
+    readonly runtime: InstalledShaderRuntime;
+    readonly inputs: ReadonlyMap<string, Readonly<Record<string, string>>>;
+    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<WrittenShaderArtifacts>;
+
+interface ShaderBrowserReadiness {
+    readonly workerReady: boolean;
+    readonly assetsReady: boolean;
+    readonly textReady: boolean;
+    readonly compileEnd: boolean;
+    readonly firstFrame: boolean;
+}
+interface ShaderBrowserObservation {
+    readonly scene: string;
+    readonly mode: 'live' | 'precompiled';
+    readonly compatibility: string;
+    readonly transform: number;
+    readonly readiness: ShaderBrowserReadiness;
+    readonly stats: ShaderCaptureStats;
+    /** Application animation frame frozen for deterministic live/precompiled parity. */
+    readonly frame: number;
+    readonly screenshot: Buffer;
+    readonly errors: readonly string[];
+}
+interface ShaderPublishedObservation extends ShaderBrowserObservation {
+    /** Primary renderer canvas before the normal-lifecycle soak. */
+    readonly beforeScreenshot: Buffer;
+}
+interface ShaderBrowserDriver {
+    capture(scene: ShaderSceneConfig, config: ShaderToolConfig): Promise<unknown>;
+    observe(scene: ShaderSceneConfig, mode: 'live' | 'precompiled', config: ShaderToolConfig, targetFrame?: number): Promise<ShaderBrowserObservation>;
+    /** Observe the published route with strict precompiled telemetry enabled. */
+    observePublished(scene: ShaderSceneConfig, config: ShaderToolConfig): Promise<ShaderPublishedObservation>;
+    timingEnvironment?(): PromiseLike<ShaderTimingEnvironment> | ShaderTimingEnvironment;
+    close(): Promise<void>;
+}
+interface PlaywrightShaderDriverOptions {
+    readonly root: string;
+    readonly runtime: InstalledShaderRuntime;
+    readonly headed?: boolean;
+}
+interface StaticPlaywrightShaderDriverOptions extends PlaywrightShaderDriverOptions {
+    /** Project-relative directory containing the already-built application. */
+    readonly serve: string;
+}
+interface AttachedPlaywrightShaderDriverOptions extends PlaywrightShaderDriverOptions {
+    /** Already-running application origin or base URL. */
+    readonly url: string;
+}
+declare function isRetryableShaderObservationNavigation(error: unknown): boolean;
+declare function createPlaywrightShaderDriver(options: PlaywrightShaderDriverOptions): ShaderBrowserDriver;
+/** Capture and verify an already-built app without loading Vite from the target project. */
+declare function createStaticPlaywrightShaderDriver(options: StaticPlaywrightShaderDriverOptions): ShaderBrowserDriver;
+/** Attach capture and parity transport to an already-running transformed application. */
+declare function createAttachedPlaywrightShaderDriver(options: AttachedPlaywrightShaderDriverOptions): ShaderBrowserDriver;
+
+interface ShaderScreenshotMetrics {
+    readonly width: number;
+    readonly height: number;
+    /** Average alpha-weighted sRGB luminance in the range 0...1. */
+    readonly luminance: number;
+}
+interface ShaderParityResult extends ShaderScreenshotMetrics {
+    readonly differentPixels: number;
+    readonly totalPixels: number;
+    readonly diffRatio: number;
+    readonly maximumChannelDelta: number;
+    readonly baselineLuminance: number;
+    readonly precompiledLuminance: number;
+    readonly nonBlack: boolean;
+    readonly matches: boolean;
+    readonly diff: Buffer;
+}
+declare function shaderScreenshotMetrics(source: Uint8Array): ShaderScreenshotMetrics;
+declare function compareShaderScreenshots(baselineSource: Uint8Array, precompiledSource: Uint8Array, channelTolerance: number, maxDiffRatio: number): ShaderParityResult;
+
+/** Snapshot declared scene inputs, or discover shader roots and their local runtime import closure. */
+declare function snapshotShaderInputs(root: string, declaredInputs?: readonly string[]): Promise<Readonly<Record<string, string>>>;
+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<InstalledShaderRuntime>;
+
+type ShaderMatrixState = 'fresh' | 'stale' | 'invalid' | 'missing';
+interface ShaderSceneArtifactStatus {
+    readonly scene: string;
+    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): Promise<ShaderMatrixStatus>;
+
+interface CaptureShadersOptions {
+    readonly start?: string;
+    readonly root?: string;
+    readonly config?: ShaderToolConfig;
+    readonly driver?: ShaderBrowserDriver;
+    /** Built-output capture bypasses Vite in the target project. */
+    readonly driverKind?: 'vite' | 'static';
+    /** Project-relative built directory used by the static driver. */
+    readonly serve?: string;
+    /** Attach to an already-running transformed application. */
+    readonly url?: string;
+    readonly headed?: boolean;
+    readonly ifStale?: boolean;
+    readonly attempts?: number;
+    /** Progress hook fired before each scene capture begins. */
+    readonly onSceneStart?: (scene: string, index: number, total: number) => void;
+    /** Progress hook fired before a failed scene is retried. */
+    readonly onSceneRetry?: (scene: string, attempt: number, total: number, timeoutMs: number, error: unknown) => void;
+}
+interface CaptureSceneResult {
+    readonly scene: string;
+    readonly attempts: number;
+    readonly coverage: ShaderCoverage;
+    readonly skipped: number;
+    /** Measured registered TSL builds in the live capture. */
+    readonly startupBuilds: number;
+    /** Measured CPU time spent in those live NodeBuilder calls. */
+    readonly startupBuildMs: number;
+    readonly timing?: ValidatedShaderCapture['timing'];
+}
+interface ShaderStartupMeasurement {
+    readonly beforeBuilds: number;
+    readonly afterBuilds: 0;
+    /** Negative measured NodeBuilder time removed from the first-frame critical path. */
+    readonly firstFrameDeltaMs: number;
+    readonly source: 'capture-build-phase';
+}
+interface CaptureShadersResult {
+    readonly schemaVersion: 1;
+    readonly root: string;
+    readonly skipped: boolean;
+    readonly reason: string;
+    readonly durationMs?: number;
+    readonly scenes: readonly CaptureSceneResult[];
+    readonly measurement?: ShaderStartupMeasurement;
+    readonly configuration?: {
+        readonly created: boolean;
+        readonly file: string;
+    };
+    readonly written?: WrittenShaderArtifacts;
+    readonly timing?: ShaderTiming;
+}
+/** Run isolated browser captures and checkpoint updates against an existing complete matrix. */
+declare function captureShaders(options?: CaptureShadersOptions): Promise<CaptureShadersResult>;
+interface TestShadersOptions {
+    readonly start?: string;
+    readonly root?: string;
+    readonly config?: ShaderToolConfig;
+    readonly driver?: ShaderBrowserDriver;
+    readonly driverKind?: 'vite' | 'static';
+    readonly serve?: string;
+    readonly url?: string;
+    readonly headed?: boolean;
+    readonly skipBrowser?: boolean;
+    /** Measured live/precompiled pairs after one discarded warmup. Defaults to 5. */
+    readonly runs?: number;
+    /** Run one live/precompiled correctness pair per scene without timing or published-page soak. */
+    readonly parityOnly?: boolean;
+    /** Also write the opt-in, hardware-labeled committed timing twin. */
+    readonly commitTiming?: boolean;
+    /** Progress hook fired before each scene observation begins. */
+    readonly onSceneStart?: (scene: string, index: number, total: number) => void;
+    /** Progress hook fired after a parity-only scene fails and verification continues. */
+    readonly onSceneError?: (scene: string, error: unknown) => void;
+}
+interface ShaderSceneTestResult {
+    readonly scene: string;
+    readonly coverage: ShaderCoverage;
+    readonly live: Omit<ShaderBrowserObservation, 'screenshot'>;
+    readonly precompiled: Omit<ShaderBrowserObservation, 'screenshot'>;
+    readonly published?: Omit<ShaderPublishedObservation, 'beforeScreenshot' | 'screenshot'>;
+    readonly parity: Omit<ShaderParityResult, 'diff'>;
+    readonly runtimeMotion?: {
+        readonly differentPixels: number;
+        readonly totalPixels: number;
+        readonly diffRatio: number;
+    };
+}
+interface TestShadersResult {
+    readonly schemaVersion: 1;
+    readonly root: string;
+    readonly noGpu: ShaderMatrixStatus;
+    readonly browser: 'passed' | 'skipped';
+    readonly scenes: readonly ShaderSceneTestResult[];
+    readonly timing?: ShaderLocalTiming;
+    readonly committedTiming?: ShaderCommittedTiming;
+}
+/** Validate freshness, zero registered builds (render and compute), and deterministic pixels. */
+declare function testShaders(options?: TestShadersOptions): Promise<TestShadersResult>;
+
+type ShaderState = 'precompiled' | 'live' | 'stale' | 'invalid' | 'missing';
+type ShaderFreshness = 'fresh' | 'stale' | 'invalid' | 'missing';
+type TextState = 'ready' | 'generating' | 'fallback' | 'missing' | 'invalid';
+type RuntimeState = 'starting' | 'worker ready' | 'assets ready' | 'compiled' | 'first frame' | 'updating' | 'error';
+type RuntimeObservation = RuntimeState;
+type RuntimeBackend = 'OffscreenCanvas' | 'MainThread';
+declare const RUNTIME_STATUS_RECEIPT_PATH = ".three-blocks/runtime/status.json";
+declare const RUNTIME_STATUS_RECEIPT_MAX_BYTES: number;
+declare const RUNTIME_STATUS_RECOVERY = "three-blocks browser smoke";
+interface RuntimeCodecObservation {
+    readonly name: string;
+    readonly available: boolean;
+    readonly decoded: boolean;
+}
+interface RuntimeHmrCapabilities {
+    readonly scene: boolean;
+    readonly component: boolean;
+    readonly assetManifest: boolean;
+    readonly workerRestart: boolean;
+}
+interface RuntimeHmrOutcome {
+    readonly attempted: boolean;
+    readonly succeeded: boolean | null;
+    readonly rollbackPreserved: boolean | null;
+    readonly workerRestarted: boolean;
+}
+interface RuntimeStatusReceiptV1 {
+    readonly schemaVersion: 1;
+    readonly observedAt: string;
+    readonly worker: {
+        readonly backend: RuntimeBackend;
+        readonly renderer: 'WebGPU' | 'WebGL';
+        readonly protocolVersion: 1;
+    };
+    readonly assets: {
+        readonly codecs: readonly RuntimeCodecObservation[];
+        readonly resources: number;
+    };
+    readonly hmr: {
+        readonly capabilities: RuntimeHmrCapabilities;
+        readonly outcome: RuntimeHmrOutcome;
+    };
+    readonly stats: {
+        readonly snapshots: number;
+        readonly textures: number;
+        readonly workerProfiler: boolean;
+        readonly mainPanels: boolean;
+    };
+    readonly lifecycle: {
+        readonly state: RuntimeState;
+        readonly workerReady: boolean;
+        readonly assetsReady: boolean;
+        readonly compiled: boolean;
+        readonly firstFrame: boolean;
+    };
+    readonly shaders: {
+        readonly mode: 'precompiled' | 'live';
+        readonly pipelines: number;
+    };
+    readonly text?: {
+        readonly state: TextState;
+        readonly atlases: number;
+        readonly glyphs: number;
+        readonly requiredGlyphs: number;
+    };
+    readonly error: string | null;
+}
+interface ShaderStatus {
+    readonly state: ShaderFreshness;
+    readonly scene: string;
+    readonly reason: string;
+    readonly coverage?: ShaderCoverage;
+    readonly changedInputs?: readonly string[];
+    readonly addedInputs?: readonly string[];
+    readonly removedInputs?: readonly string[];
+}
+interface TextAtlasStatus {
+    readonly name: string;
+    readonly glyphs: number;
+    readonly width: number;
+    readonly height: number;
+}
+interface TextStatus {
+    readonly state: TextState;
+    readonly reason: string;
+    readonly atlases: readonly TextAtlasStatus[];
+}
+interface RuntimeWorkerStatus {
+    readonly state: RuntimeState;
+    readonly backend: RuntimeStatusReceiptV1['worker']['backend'] | null;
+    readonly renderer: RuntimeStatusReceiptV1['worker']['renderer'] | null;
+    readonly protocolVersion: 1;
+}
+interface RuntimeAssetsStatus {
+    readonly state: RuntimeState;
+    readonly codecs: readonly RuntimeCodecObservation[];
+    readonly resources: number;
+}
+interface RuntimeHmrStatus {
+    readonly state: RuntimeState;
+    readonly capabilities: RuntimeHmrCapabilities;
+    readonly outcome: RuntimeHmrOutcome;
+}
+interface RuntimeStatsStatus {
+    readonly state: RuntimeState;
+    readonly snapshots: number;
+    readonly textures: number;
+    readonly workerProfiler: boolean;
+    readonly mainPanels: boolean;
+}
+interface RuntimeOptimizationStatus {
+    readonly state: RuntimeState | ShaderState | ShaderFreshness;
+    readonly mode: RuntimeStatusReceiptV1['shaders']['mode'] | null;
+    readonly pipelines: number;
+    readonly artifactState: ShaderFreshness;
+}
+interface RuntimeTextStatus {
+    readonly state: RuntimeState | TextState;
+    readonly atlases: number;
+    readonly glyphs: number;
+    readonly requiredGlyphs: number;
+}
+interface ProjectStatus {
+    readonly schemaVersion: 1;
+    readonly root: string;
+    readonly metadata: ProjectMetadataV2;
+    readonly configuration: {
+        readonly worker: RuntimeWorkerStatus;
+        readonly assets: RuntimeAssetsStatus;
+        readonly hmr: RuntimeHmrStatus;
+        readonly optimization: RuntimeOptimizationStatus;
+        readonly stats: RuntimeStatsStatus;
+        readonly text?: RuntimeTextStatus;
+    };
+    readonly runtime: {
+        readonly state: RuntimeState;
+        readonly observed: boolean;
+        readonly observedAt: string | null;
+        readonly reason: string;
+        readonly recovery: string;
+        readonly observation: RuntimeStatusReceiptV1 | null;
+    };
+    readonly shaders: ShaderStatus;
+    readonly text?: TextStatus;
+}
+interface AdoptedProjectStatus {
+    readonly schemaVersion: 1;
+    readonly root: string;
+    readonly kind: 'adopted';
+    readonly markers: {
+        readonly shaders: boolean;
+        readonly text: boolean;
+    };
+    readonly shaders?: ShaderMatrixStatus;
+    readonly text?: TextAtlasInspection;
+}
+type ThreeBlocksStatus = ProjectStatus | AdoptedProjectStatus;
+/** Strict parser for the browser-owned observation receipt consumed by `three-blocks status`. */
+declare function parseRuntimeStatusReceipt(value: unknown): RuntimeStatusReceiptV1;
+declare function findProjectRoot(start?: string): Promise<string>;
+declare function inspectProject(start?: string): Promise<ProjectStatus>;
+/**
+ * Inspect metadata-aware projects or compose the public markers independently
+ * adopted by any other application. Unknown private metadata never blocks the
+ * public shader/text status surface.
+ */
+declare function inspectThreeBlocksStatus(start?: string): Promise<ThreeBlocksStatus>;
+/** Whether `status --check` should accept the composed report. */
+declare function threeBlocksStatusIsFresh(report: ThreeBlocksStatus): boolean;
+/** Shared shaders-status formatter used by both commands. */
+declare function formatShaderMatrixStatus(report: ShaderMatrixStatus): string;
+/**
+ * The human status view. Committed artifacts and installed versions are facts;
+ * a browser observation is evidence with an age — it is labeled as such instead
+ * of rendering unobserved runtime rows as an alarming wall of "starting".
+ */
+declare function formatStatus(report: ProjectStatus, now?: number): string;
+/** Human status output for either starter metadata or independently adopted markers. */
+declare function formatThreeBlocksStatus(report: ThreeBlocksStatus, now?: number): string;
+
+type TextUnicodePreset = 'latin' | 'japanese-kana';
+interface TextUnicodeRange {
+    readonly start: number;
+    readonly end: number;
+}
+interface GlyphSetOptions {
+    readonly presets?: readonly TextUnicodePreset[];
+    readonly ranges?: readonly TextUnicodeRange[];
+    readonly additionalCharacters?: string;
+}
+interface GlyphSet {
+    readonly codePoints: readonly number[];
+    readonly characters: string;
+    readonly hash: string;
+}
+/** Extract only visible text nested under the public `data-canvas-text` marker. */
+declare function extractCanvasTextFromHtml(html: string): readonly string[];
+/** Extract string values only from helpers imported from the public text entrypoint. */
+declare function extractDefinedTextContent(source: string, fileName?: string): readonly string[];
+/** Normalize, deduplicate, and deterministically sort the closed-world glyph set. */
+declare function buildGlyphSet(content: readonly string[], options?: GlyphSetOptions): GlyphSet;
+
+interface ToolTextFontSourceBuiltin {
+    readonly builtin: string;
+}
+interface ToolTextFontSourcePath {
+    readonly path: string;
+}
+interface ToolTextFontSourcePackage {
+    readonly package: string;
+    readonly file: string;
+    readonly checksum: string;
+}
+type ToolTextFontSource = ToolTextFontSourceBuiltin | ToolTextFontSourcePath | ToolTextFontSourcePackage;
+interface ToolTextFontRoute {
+    readonly source: ToolTextFontSource;
+    readonly browser: string;
+    readonly atlas: string;
+    readonly metrics: string;
+    readonly families: readonly string[];
+    readonly languages: readonly string[];
+    readonly default: boolean;
+}
+interface ToolTextGenerationOptions extends GlyphSetOptions {
+    readonly presets?: readonly TextUnicodePreset[];
+    readonly ranges?: readonly TextUnicodeRange[];
+    readonly size?: number;
+    readonly distanceRange?: number;
+    readonly padding?: number;
+    readonly maxTextureSize?: number;
+}
+interface ToolTextConfiguration {
+    readonly schemaVersion: 1;
+    readonly content: readonly string[];
+    readonly fonts: Readonly<Record<string, ToolTextFontRoute>>;
+    readonly generation: ToolTextGenerationOptions;
+}
+interface DiscoveredTextContent {
+    readonly values: readonly string[];
+    readonly glyphs: GlyphSet;
+    readonly inputs: Readonly<Record<string, string>>;
+}
+/** Parse one statically authored `defineText()` call without executing project code. */
+declare function parseTextConfiguration(source: string, fileName?: string): ToolTextConfiguration;
+declare function readTextConfiguration(root: string, relativePath?: string): Promise<ToolTextConfiguration>;
+/** Read only configured semantic inputs and compute the content-sensitive glyph fingerprint. */
+declare function discoverTextContent(root: string, configuration: ToolTextConfiguration): Promise<DiscoveredTextContent>;
+
+/**
+ * Ambient Chromium/Three.js diagnostics that do not describe an application failure.
+ *
+ * Keep this list intentionally small. A new suppression is a public behavior change and
+ * should name the upstream diagnostic it is suppressing.
+ */
+declare const DOCUMENTED_BROWSER_NOISE: readonly [{
+    readonly id: "three-inspector-invalid-json";
+    readonly pattern: RegExp;
+}, {
+    readonly id: "chromium-webgpu-experimental";
+    readonly pattern: RegExp;
+}];
+declare function isDocumentedBrowserNoise(message: string): boolean;
+/** Chromium launch flags used by public WebGPU browser tools. */
+declare function webgpuBrowserArgs(environment?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): readonly string[];
+/** Lavapipe is most reliable in Chromium's headful mode under Xvfb. */
+declare function webgpuBrowserHeadless(headed?: boolean, environment?: NodeJS.ProcessEnv): boolean;
+
+interface BrowserSmokeOptions {
+    readonly root: string;
+    /** Project URL below Vite's configured base. Defaults to `/`. */
+    readonly route?: string;
+    readonly timeoutMs?: number;
+    readonly settleMs?: number;
+    readonly headed?: boolean;
+    readonly viewport?: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /** Minimum mean center-frame or readable-panel luminance. Defaults to 2. */
+    readonly minimumLuminance?: number;
+    /** Optional project-relative scene module to invalidate through Vite's real HMR pipeline. */
+    readonly hmrModule?: string;
+    /** Exercise the worker-owned WebGL fallback by hiding WebGPU before application code runs. */
+    readonly forceWebgl?: boolean;
+    /** Exercise the visible fatal path by hiding the Worker API before application code runs. */
+    readonly unsupportedWorker?: boolean;
+    /** Treat a visible, unrecovered text fallback plus one actionable Vite warning as the expected outcome. */
+    readonly expectTextGenerationFailure?: boolean;
+}
+interface BrowserSmokeLifecycle {
+    readonly source: 'public' | 'legacy' | 'missing';
+    readonly backend: 'OffscreenCanvas' | 'MainThread' | 'unknown';
+    readonly worker: boolean;
+    readonly workerReady: boolean;
+    readonly assetsReady: boolean;
+    readonly compileEnd: boolean;
+    readonly textEnabled: boolean;
+    readonly textReady: boolean;
+    readonly firstFrame: boolean;
+}
+interface BrowserSmokeCodecRoute {
+    readonly route: string;
+    readonly bytes: number;
+    readonly contentType: string;
+}
+interface BrowserSmokeCodec {
+    readonly name: 'draco' | 'ktx2' | 'meshopt';
+    readonly state: 'ready' | 'disabled' | 'error';
+    readonly routes: readonly BrowserSmokeCodecRoute[];
+    readonly decoded: boolean;
+    readonly evidence: 'delivery' | 'decoder-ready' | 'text-atlas-decoded' | 'asset-manager-decoded';
+    readonly blocker: string | null;
+    readonly error: string | null;
+}
+interface BrowserSmokeHmrEvidence {
+    readonly sceneIdentityReplaced: boolean;
+    readonly stateRestored: boolean;
+    readonly assetIdentityPreserved: boolean;
+    readonly assetReferencesPreserved: boolean;
+    readonly statsIdentityPreserved: boolean;
+    readonly statsSequenceAdvanced: boolean;
+    readonly shaderInvalidated: boolean;
+    readonly rollbackPreserved: boolean;
+}
+interface BrowserSmokeWorkerRestart {
+    readonly requested: boolean;
+    readonly appIdentityStable: boolean;
+    readonly contentIdentityStable: boolean;
+    readonly canvasReplaced: boolean;
+    readonly workerIdentityChanged: boolean;
+    readonly generationAdvanced: boolean;
+    readonly restartCountAdvanced: boolean;
+    readonly stateReplayed: boolean;
+    readonly readinessRestored: boolean;
+    readonly shaderModeStable: boolean;
+    readonly statsSnapshotsAdvanced: boolean;
+    readonly statsTextureTransferred: boolean;
+    readonly statsTextureStopped: boolean;
+    readonly error: string | null;
+}
+interface BrowserSmokeHmr {
+    readonly requested: boolean;
+    readonly module: string | null;
+    readonly dispatched: boolean;
+    readonly acknowledged: boolean;
+    readonly lifecycleStable: boolean;
+    readonly sourceUnchanged: boolean;
+    readonly evidenceSource: 'public-runtime-browser-probe';
+    readonly evidence: BrowserSmokeHmrEvidence;
+    readonly restart: BrowserSmokeWorkerRestart;
+    readonly error: string | null;
+}
+interface BrowserSmokeBuildReceipt {
+    readonly schemaVersion: 2;
+    readonly renderer: {
+        readonly owner: 'worker';
+        readonly api: 'WebGPU';
+        readonly fallback: 'WebGL';
+    };
+    readonly assets: {
+        readonly draco: 'ready' | 'disabled';
+        readonly ktx2: 'ready' | 'disabled';
+        readonly meshopt: 'lazy' | 'disabled';
+    };
+    readonly shaders: {
+        readonly state: 'fresh' | 'stale' | 'invalid' | 'missing';
+        readonly mode: 'precompiled' | 'live';
+        readonly pipelines: number;
+    };
+    readonly text?: {
+        readonly state: 'ready' | 'generating' | 'fallback' | 'missing' | 'invalid';
+        readonly atlases: number;
+        readonly glyphs: number;
+    };
+    readonly stats: {
+        readonly enabled: boolean;
+        readonly production: boolean;
+    };
+    readonly output: string;
+    readonly threeVersion: string;
+}
+interface BrowserSmokeReport {
+    readonly schemaVersion: 1;
+    readonly command: 'browser smoke';
+    readonly passed: boolean;
+    readonly scene: string;
+    readonly lifecycle: BrowserSmokeLifecycle;
+    readonly renderer: {
+        readonly requested: 'WebGPU-first' | 'WebGL-fallback' | 'unsupported-worker';
+        readonly active: 'WebGPU' | 'WebGL' | 'none' | 'unknown';
+        readonly navigatorGpu: boolean;
+        readonly workerOwned: boolean;
+        readonly fallbackDiagnostic: boolean;
+    };
+    readonly compatibility: {
+        readonly fatalVisible: boolean;
+        readonly code: string | null;
+        readonly detail: string | null;
+        readonly silentMainThreadRenderer: boolean;
+    };
+    readonly receipt: BrowserSmokeBuildReceipt | null;
+    readonly textFallback: {
+        readonly states: readonly string[];
+        readonly fallbackObserved: boolean;
+        readonly recovered: boolean;
+        readonly visibleElements: number;
+        readonly totalElements: number;
+    };
+    readonly warnings: readonly string[];
+    readonly rendering: {
+        readonly luminance: number;
+        readonly panelLuminance: number;
+        readonly threshold: number;
+        readonly blackFrame: boolean;
+    };
+    readonly codecs: readonly BrowserSmokeCodec[];
+    readonly hmr: BrowserSmokeHmr;
+    readonly errors: {
+        readonly console: readonly string[];
+        readonly page: readonly string[];
+        readonly resolved: readonly string[];
+    };
+}
+/** Parse the public smoke bridge, with a bounded compatibility path for the integration lab. */
+declare function parseBrowserSmokeLifecycle(snapshot: unknown, textEnabled: boolean): BrowserSmokeLifecycle;
+declare function screenshotLuminance(bytes: Uint8Array): number;
+/** Boot a project's Vite config and verify its real browser/worker runtime. */
+declare function runBrowserSmoke(options: BrowserSmokeOptions): Promise<BrowserSmokeReport>;
+declare function formatBrowserSmokeReport(report: BrowserSmokeReport): string;
+interface BrowserPreviewOptions {
+    readonly root: string;
+    /** Project URLs below Vite's configured base, all verified against one production build. */
+    readonly routes?: readonly string[];
+    /** Vite mode for the production build; `"strict"` is a common release mode. */
+    readonly buildMode?: string;
+    /** Shader runtime mode every route must report. Defaults to `precompiled`. */
+    readonly expectShaders?: 'precompiled' | 'live';
+    /** Routes must also reach text readiness. */
+    readonly text?: boolean;
+    readonly timeoutMs?: number;
+    readonly settleMs?: number;
+    readonly headed?: boolean;
+    readonly viewport?: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /** Minimum mean center-frame or readable-panel luminance. Defaults to 2. */
+    readonly minimumLuminance?: number;
+}
+interface BrowserPreviewRouteReport {
+    readonly route: string;
+    readonly passed: boolean;
+    readonly lifecycle: BrowserSmokeLifecycle;
+    readonly shaderMode: 'precompiled' | 'live' | null;
+    readonly rendering: {
+        readonly luminance: number;
+        readonly panelLuminance: number;
+        readonly threshold: number;
+        readonly blackFrame: boolean;
+    };
+    readonly errors: {
+        readonly console: readonly string[];
+        readonly page: readonly string[];
+    };
+}
+interface BrowserPreviewReport {
+    readonly schemaVersion: 1;
+    readonly command: 'browser preview';
+    readonly passed: boolean;
+    readonly buildMode: string | null;
+    readonly expectShaders: 'precompiled' | 'live';
+    readonly routes: readonly BrowserPreviewRouteReport[];
+}
+/**
+ * Build the project's real production bundle and verify each route against `vite preview`:
+ * worker lifecycle, non-black rendering, the reported shader runtime mode, and an
+ * error-free console. Dev-server smokes never exercise minified worker chunks, so this is
+ * the gate that catches precompiled-shader hydration regressions in shipped output.
+ */
+declare function runBrowserPreview(options: BrowserPreviewOptions): Promise<BrowserPreviewReport>;
+declare function formatBrowserPreviewReport(report: BrowserPreviewReport): string;
+
+declare const ENVIRONMENT_BAKE_VERSION: 1;
+interface RoomEnvironmentMetadata {
+    readonly compression: 'zstd' | 'none';
+    readonly cubeSize: number;
+    readonly format: 'RGBA16F CubeUVReflectionMapping';
+    readonly height: number;
+    readonly rawBytes: number;
+    readonly sha256: string;
+    readonly three: string;
+    readonly version: typeof ENVIRONMENT_BAKE_VERSION;
+    readonly width: number;
+}
+interface EncodedRoomEnvironment {
+    readonly bytes: Uint8Array;
+    readonly metadata: RoomEnvironmentMetadata;
+}
+interface RoomEnvironmentCaptureResult {
+    readonly bytes: Uint8Array;
+    readonly threeRevision: string;
+}
+interface RoomEnvironmentCaptureOptions {
+    readonly root: string;
+    readonly size: number;
+    readonly timeoutMs: number;
+    readonly headed: boolean;
+}
+type RoomEnvironmentCapture = (options: RoomEnvironmentCaptureOptions) => Promise<RoomEnvironmentCaptureResult>;
+interface EnvironmentBakeOptions {
+    readonly root: string;
+    readonly size?: number;
+    readonly output?: string;
+    readonly timeoutMs?: number;
+    readonly compression?: 'zstd' | 'none';
+    readonly headed?: boolean;
+    /** Dependency-injection seam for deterministic tests and alternate browser farms. */
+    readonly capture?: RoomEnvironmentCapture;
+}
+interface EnvironmentBakeReport {
+    readonly schemaVersion: 1;
+    readonly command: 'environment bake';
+    readonly output: string;
+    readonly metadataOutput: string;
+    readonly bytes: number;
+    readonly metadata: RoomEnvironmentMetadata;
+}
+declare function validateEnvironmentCubeSize(value: number): number;
+/** Deterministically zstd-encode and fully round-trip an exported RGBA16F CubeUV KTX2. */
+declare function encodeRoomEnvironmentKtx2(rawBytes: Uint8Array, options: {
+    readonly cubeSize: number;
+    readonly threeRevision: string;
+    readonly compression?: 'zstd' | 'none';
+}): EncodedRoomEnvironment;
+/** Capture the procedural environment in a real Chromium WebGPU renderer. */
+declare const captureRoomEnvironment: RoomEnvironmentCapture;
+/** Render, encode, verify, and atomically commit the public RoomEnvironment artifact pair. */
+declare function bakeRoomEnvironment(options: EnvironmentBakeOptions): Promise<EnvironmentBakeReport>;
+declare function formatEnvironmentBakeReport(report: EnvironmentBakeReport): string;
+
+declare function loadShaderCaptureRuntimeSource(): Promise<string>;
+
+interface ShaderWatchQueueOptions {
+    readonly capture: () => Promise<void>;
+    readonly debounceMs?: number;
+    readonly onError?: (error: Error) => void;
+}
+/** Debounced capture queue with at most one running capture and one queued rerun. */
+declare class ShaderWatchQueue {
+    #private;
+    constructor(options: ShaderWatchQueueOptions);
+    notify(): void;
+    close(): Promise<void>;
+}
+interface WatchShadersOptions extends Omit<CaptureShadersOptions, 'root' | 'ifStale'> {
+    readonly root?: string;
+    readonly debounceMs?: number;
+    readonly signal?: AbortSignal;
+    readonly onResult?: (result: CaptureShadersResult) => void;
+    readonly onError?: (error: Error) => void;
+    readonly initial?: boolean;
+}
+interface ShaderWatchSession {
+    readonly root: string;
+    readonly done: Promise<void>;
+    close(): Promise<void>;
+}
+/** Opt-in filesystem watch. A failed recapture leaves the prior receipt in place and watching continues. */
+declare function watchShaders(options?: WatchShadersOptions): Promise<ShaderWatchSession>;
+
+export { type AdoptedProjectStatus, type ArtifactState, type AttachedPlaywrightShaderDriverOptions, type BrowserPreviewOptions, type BrowserPreviewReport, type BrowserPreviewRouteReport, type BrowserSmokeBuildReceipt, type BrowserSmokeCodec, type BrowserSmokeCodecRoute, type BrowserSmokeHmr, type BrowserSmokeHmrEvidence, type BrowserSmokeLifecycle, type BrowserSmokeOptions, type BrowserSmokeReport, type BrowserSmokeWorkerRestart, type BuiltinFontMetadata, type CaptureSceneResult, type CaptureShadersOptions, type CaptureShadersResult, DOCUMENTED_BROWSER_NOISE, type DiscoveredTextContent, type EncodedRoomEnvironment, type EnsuredShaderToolConfig, type EnvironmentBakeOptions, type EnvironmentBakeReport, type GenerateTextResult, type GeneratedTextAtlas, type GlyphSet, type GlyphSetOptions, type InferredShaderCaptureTarget, type InstalledShaderRuntime, type PlaywrightShaderDriverOptions, type ProjectMetadataV2, type ProjectStatus, RUNTIME_STATUS_RECEIPT_MAX_BYTES, RUNTIME_STATUS_RECEIPT_PATH, RUNTIME_STATUS_RECOVERY, type RoomEnvironmentCapture, type RoomEnvironmentCaptureOptions, type RoomEnvironmentCaptureResult, type RoomEnvironmentMetadata, type RuntimeAssetsStatus, type RuntimeBackend, type RuntimeCodecObservation, type RuntimeHmrCapabilities, type RuntimeHmrOutcome, type RuntimeHmrStatus, type RuntimeObservation, type RuntimeOptimizationStatus, type RuntimeState, type RuntimeStatsStatus, type RuntimeStatusReceiptV1, type RuntimeTextStatus, type RuntimeWorkerStatus, SHADER_ARTIFACT_DIRECTORY, SHADER_COMMITTED_TIMING_FILE, SHADER_DEVTOOLS_VERSION, SHADER_LOCAL_TIMING_FILE, SHADER_PARITY_DIRECTORY, SHADER_PARITY_EVIDENCE_FILE, SHADER_PROVIDER_TRANSFORM_VERSION, SHADER_TOOL_CONFIG_FILE, type ShaderBridgeConfig, type ShaderBrowserDriver, type ShaderBrowserObservation, type ShaderBrowserReadiness, type ShaderCapturePayload, type ShaderCaptureProvenance, type ShaderCaptureStageTiming, type ShaderCaptureStats, type ShaderCommittedTiming, type ShaderCoverage, type ShaderFreshness, type ShaderLocalTiming, type ShaderMatrixState, type ShaderMatrixStatus, type ShaderParityConfig, type ShaderParityEvidence, type ShaderParityResult, type ShaderReadinessConfig, type ShaderReceiptV2, type ShaderSceneArtifactStatus, type ShaderSceneConfig, type ShaderSceneParityEvidence, type ShaderSceneReceipt, type ShaderSceneTestResult, type ShaderSceneTiming, type ShaderScreenshotMetrics, type ShaderSkippedBuild, type ShaderStartupMeasurement, type ShaderState, type ShaderStatus, type ShaderTiming, type ShaderTimingEnvironment, type ShaderToolConfig, ShaderWatchQueue, type ShaderWatchQueueOptions, type ShaderWatchSession, type StaticPlaywrightShaderDriverOptions, TEXT_ATLAS_GENERATOR_VERSION, TEXT_ATLAS_SCHEMA_VERSION, type TestShadersOptions, type TestShadersResult, type TextAtlasFileReceipt, type TextAtlasGenerationReceipt, type TextAtlasInspection, type TextAtlasRuntimeOptions, type TextAtlasStatus, type TextState, type TextStatus, type TextUnicodePreset, type TextUnicodeRange, type ThreeBlocksStatus, type ToolTextConfiguration, type ToolTextFontRoute, type ToolTextFontSource, type ToolTextGenerationOptions, type ValidateShaderCaptureOptions, type ValidatedShaderCapture, type WatchShadersOptions, type WriteShaderArtifactsOptions, type WrittenShaderArtifacts, bakeRoomEnvironment, buildGlyphSet, builtinFontMetadata, captureRoomEnvironment, captureShaders, compareShaderScreenshots, createAttachedPlaywrightShaderDriver, createPlaywrightShaderDriver, createStaticPlaywrightShaderDriver, discoverTextContent, encodeRoomEnvironmentKtx2, ensureShaderToolConfig, extractCanvasTextFromHtml, extractDefinedTextContent, findProjectRoot, findShaderProjectRoot, formatBrowserPreviewReport, formatBrowserSmokeReport, formatEnvironmentBakeReport, formatShaderMatrixStatus, formatStatus, formatThreeBlocksStatus, generateTextAtlases, inferShaderCaptureTarget, inspectProject, inspectShaderMatrix, inspectTextAtlases, inspectThreeBlocksStatus, isDocumentedBrowserNoise, isRetryableShaderObservationNavigation, loadShaderCaptureRuntimeSource, loadShaderToolConfig, parseBrowserSmokeLifecycle, parseProjectMetadata, parseRuntimeStatusReceipt, parseShaderReceipt, parseShaderToolConfig, parseTextAtlasReceipt, parseTextConfiguration, prewarmBuiltinFont, readInstalledShaderRuntime, readShaderCommittedTiming, readShaderLocalTiming, readShaderParityEvidence, readShaderTiming, readTextConfiguration, runBrowserPreview, runBrowserSmoke, screenshotLuminance, serializeShaderManifest, shaderCoverage, shaderScreenshotMetrics, snapshotShaderInputs, stableStringify, testShaders, threeBlocksStatusIsFresh, validateEnvironmentCubeSize, validateShaderCapture, watchShaders, webgpuBrowserArgs, webgpuBrowserHeadless, writeShaderArtifacts, writeShaderLocalTiming, writeShaderParityEvidence, writeShaderTimingTwins };