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-D160zMyt.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 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>; } 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; 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; /** Per-weight atlas instances keyed by CSS weight, present when the route declares weights. */ readonly weights?: Readonly>; }; } 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; /** Generate every configured atlas only from semantically declared text content. */ declare function generateTextAtlases(root: string, configurationPath?: string, runtimeOptions?: TextAtlasRuntimeOptions): Promise; 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; 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"; 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 parseShaderToolConfig(value: unknown): ShaderToolConfig; declare function findShaderProjectRoot(start?: string): Promise; declare function loadShaderToolConfig(root: string): Promise; 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; /** * Materialize the convention single-scene configuration on first capture. * Existing explicit configuration and generated-project metadata remain authoritative. */ declare function ensureShaderToolConfig(root: string): Promise; /** 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: 65; 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; /** 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 ShaderTimingEnvironment { readonly adapter: string; readonly platform: string; } interface ShaderSceneParityEvidence { readonly execution?: 'node' | 'browser'; /** Binds one successful renderer comparison to its scene plus shared runtime/tool receipt inputs. */ readonly fingerprint: string; readonly verifiedAt: string; } interface ShaderParityEvidence { readonly schemaVersion: 2; readonly scenes: Readonly>; } 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 ShaderCapturePayload extends Pick { readonly protocolVersion: 2; readonly compatibility: string; readonly scene: string; readonly automatic?: { readonly prefix: string; }; readonly requiresSetup: boolean; readonly skipped: readonly ShaderSkippedBuild[]; readonly errors: readonly string[]; readonly stats: ShaderCaptureStats; readonly timing?: ShaderCaptureStageTiming; readonly provenance?: ShaderCaptureProvenance; } 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; } 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; /** Read exact timing twins, preferring the machine-local observation. */ declare function readShaderTiming(directory: string, receipt: Uint8Array): Promise; /** Read native parity evidence for the scenes that still match the current receipt. */ declare function readShaderParityEvidence(directory: string, receipt: Uint8Array): Promise; /** Read only the canonical, committed timing file for an exact receipt. */ declare function readShaderCommittedTiming(directory: string, receipt: Uint8Array): Promise; /** Persist successful build timing, bound to the exact current shader receipt. */ declare function writeShaderLocalTiming(root: string, scenes: Readonly>): Promise; /** Persist successful Node parity checkpoints for exact per-scene receipt inputs. */ declare function writeShaderParityEvidence(root: string, scenes: readonly string[], expectedReceipt?: Uint8Array): Promise; /** Persist local timing and its explicitly requested committed twin. */ declare function writeShaderTimingTwins(root: string, scenes: Readonly>, environment: ShaderTimingEnvironment): Promise<{ readonly local: ShaderLocalTiming; readonly committed: ShaderCommittedTiming; }>; 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; interface ShaderBrowserReadiness { readonly workerReady: boolean; readonly assetsReady: boolean; readonly textReady: boolean; readonly compileEnd: boolean; readonly firstFrame: boolean; } interface ShaderBrowserObservation { readonly execution?: 'node'; readonly scene: string; readonly mode: 'live' | 'precompiled'; readonly compatibility: string; readonly transform: number; readonly readiness: ShaderBrowserReadiness; readonly stats: ShaderCaptureStats; /** * Tail of the lane's shader-demand journal (builds, skips, provider probes * with lookup-time fingerprints). Diagnostic-only: consumed by identity-drift * failure messages, never by gates. */ readonly demands?: readonly Record[]; /** Application animation frame frozen for deterministic live/precompiled parity. */ readonly frame: number; /** First observable rendered frame, before configured settling. */ readonly firstFrameScreenshot: Buffer; 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, backend?: ShaderBackend): Promise; observe(scene: ShaderSceneConfig, mode: 'live' | 'precompiled', config: ShaderToolConfig, targetFrame?: number, backend?: ShaderBackend, /** Precompiled only: also live-build every hydrated key and report `stats.stateOracle`. */ stateOracle?: boolean): Promise; /** Observe the published route with strict precompiled telemetry enabled. */ observePublished(scene: ShaderSceneConfig, config: ShaderToolConfig, backend?: ShaderBackend): Promise; timingEnvironment?(): PromiseLike | ShaderTimingEnvironment; close(): Promise; } interface ShaderDriverOptions { readonly root: string; readonly runtime: InstalledShaderRuntime; readonly headed?: boolean; /** Project-relative directory containing the already-built application. */ readonly serve?: string; /** Public path the application was built for (Vite `base`); the directory answers under it too. */ readonly base?: string; /** Already-running application origin or base URL. */ readonly url?: string; } declare function isRetryableShaderObservationNavigation(error: unknown): boolean; /** Shared Node capture/parity driver for every scene. */ declare function createShaderDriver(options: ShaderDriverOptions): 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>>; 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; interface CaptureShadersOptions { readonly start?: string; readonly root?: string; readonly config?: ShaderToolConfig; /** Exact runtime identity for an attached or checkout-built application. */ readonly runtime?: InstalledShaderRuntime; 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 backend?: ShaderBackendSelection; readonly ifStale?: boolean; readonly attempts?: number; /** Also write a shareable, hardware-labeled single-capture timing estimate. */ readonly commitTiming?: boolean; /** 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 backend: ShaderBackend; 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 cumulative NodeBuilder work observed during the capture build phase. */ 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; } interface CaptureBuiltShadersOptions { readonly root: string; /** Built application directory, project-relative or absolute; its manifests are written inside it. */ readonly serve: string; /** Public path the application was built for (Vite `base`). */ readonly base?: string; readonly config?: ShaderToolConfig; readonly runtime?: InstalledShaderRuntime; readonly backend?: ShaderBackendSelection; readonly onSceneStart?: CaptureShadersOptions['onSceneStart']; readonly onSceneRetry?: CaptureShadersOptions['onSceneRetry']; } interface CaptureBuiltShadersResult { readonly durationMs: number; readonly scenes: readonly CaptureSceneResult[]; /** Project-relative manifests, one per scene and backend. */ readonly files: readonly string[]; } /** * Capture an already-built application and write `three-blocks/shaders/..json` * next to it, where the production runtime looks by convention. No receipt and no input * hashes: the manifests describe exactly this bundle, and the next build replaces both. */ declare function captureBuiltShaders(options: CaptureBuiltShadersOptions): Promise; /** Run isolated browser captures and checkpoint updates against an existing complete matrix. */ declare function captureShaders(options?: CaptureShadersOptions): Promise; interface TestShadersOptions { readonly start?: string; readonly root?: string; readonly config?: ShaderToolConfig; /** Exact runtime identity for an attached or checkout-built application. */ readonly runtime?: InstalledShaderRuntime; readonly driver?: ShaderBrowserDriver; readonly driverKind?: 'vite' | 'static'; readonly serve?: string; readonly url?: string; readonly headed?: boolean; readonly backend?: ShaderBackendSelection; 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; /** * With `parityOnly`: also run the state oracle on pairs whose pixels agree, and fail a * pair whose hydrated state differs from a live build. A pixel failure always runs it. */ readonly stateOracle?: 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 backend: ShaderBackend; readonly coverage: ShaderCoverage; readonly live: Omit; readonly precompiled: Omit; readonly published?: Omit; readonly parity: Omit; 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'; /** Native raster parity is reported separately from browser release evidence. */ readonly native?: 'passed'; readonly scenes: readonly ShaderSceneTestResult[]; readonly timing?: ShaderLocalTiming; readonly committedTiming?: ShaderCommittedTiming; } declare function testShaders(options?: TestShadersOptions): Promise; 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; declare function inspectProject(start?: string): Promise; /** * 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; /** 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 ToolTextFontWeightVariant { readonly atlas: string; readonly metrics: string; } interface ToolTextFontRoute { readonly source: ToolTextFontSource; readonly browser: string; readonly atlas: string; readonly metrics: string; /** Atlas instances baked at other CSS weights; the base atlas/metrics pair represents 400. */ readonly weights: Readonly>; 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>; readonly generation: ToolTextGenerationOptions; } interface DiscoveredTextContent { readonly values: readonly string[]; readonly glyphs: GlyphSet; readonly inputs: Readonly>; } /** 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; /** Read only configured semantic inputs and compute the content-sensitive glyph fingerprint. */ declare function discoverTextContent(root: string, configuration: ToolTextConfiguration): Promise; /** * 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; }, { readonly id: "browser-automatic-favicon"; readonly pattern: RegExp; }]; declare function isDocumentedBrowserNoise(message: string): boolean; /** @deprecated Native Node rendering needs no browser launch arguments. */ declare function webgpuBrowserArgs(_environment?: NodeJS.ProcessEnv, _platform?: NodeJS.Platform): readonly string[]; /** @deprecated Native Node rendering is always headless. */ 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-node-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 execution: 'node'; 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[]; }; } /** Shader provider counters of one page: hydrated states, provider misses, and live TSL builds. */ interface BrowserShaderCounters { readonly injected: number; readonly missed: number; readonly live: number; } /** 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; 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; /** Project-relative directory that receives one PNG of each route's settled frame. */ readonly screenshots?: string; } interface BrowserPreviewRouteReport { readonly route: string; readonly passed: boolean; readonly lifecycle: BrowserSmokeLifecycle; readonly shaderMode: 'precompiled' | 'live' | null; /** `live` above zero names shaders the bundle still compiles in the visitor's browser. */ readonly shaders?: BrowserShaderCounters; /** Project-relative PNG of the settled frame, when `screenshots` was given. */ readonly screenshot?: string; 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 execution: 'node'; 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; interface ProjectCheckReport { readonly schemaVersion: 1; readonly command: 'check'; readonly passed: boolean; /** `ran` is false when the project has no `tsconfig.json` or no local TypeScript. */ readonly typecheck: { readonly ran: boolean; readonly passed: boolean; readonly diagnostics: readonly string[]; }; /** Absent when the production build itself failed; `error` then says why. */ readonly preview?: BrowserPreviewReport; readonly error?: string; } /** * The one verification to run after an edit: the project's types, then its real production * bundle, built once (which captures its shaders) and booted natively per configured scene. * Each route reports its console errors, the shaders it still compiles live, and the PNG of * its settled frame under `.three-blocks/check/`, which is how an agent sees its change. */ declare function runProjectCheck(options: { readonly root: string; }): Promise; declare function formatProjectCheckReport(report: ProjectCheckReport): string; 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; 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 native Node WebGPU renderer. */ declare const captureRoomEnvironment: RoomEnvironmentCapture; /** Render, encode, verify, and atomically commit the public RoomEnvironment artifact pair. */ declare function bakeRoomEnvironment(options: EnvironmentBakeOptions): Promise; declare function formatEnvironmentBakeReport(report: EnvironmentBakeReport): string; declare function loadShaderCaptureRuntimeSource(): Promise; /** * Asset optimization: meshopt geometry + slot-aware Basis Universal (KTX2) * textures for GLB/image/HDR inputs, with a content-hash encode cache and a * receipt committed last. The heavy encoders (Skia, gltf-transform, * meshoptimizer, ktx2-encoder) load lazily so importing this module stays * cheap for the Vite plugin's self-inspection path. * * Verified contract (docs/plans/asset-optimize.md ยง5): `.hdr` inputs must be * Y-flipped at encode, data/normal slots must not carry the sRGB transfer in * their DFD, and LDR sources must be resized below the wasm encoder's * ~12-Mpix source ceiling before encoding. */ /** v2: exact per-mip VRAM math persisted in receipt entries (invalidates v1 caches/receipts). */ declare const ASSET_OPTIMIZE_VERSION = 2; declare const ASSET_RECEIPT_DIRECTORY: string; declare const ASSET_RECEIPT_FILE: string; type AssetKind = 'glb' | 'image' | 'hdr'; type TexturePreset = 'color' | 'normal' | 'data' | 'hdr'; type TextureEncodeMode = 'etc1s' | 'uastc' | 'uastc-hdr'; interface AssetOptimizeOptions { /** Project root: anchors the encode cache and the receipt. */ readonly root: string; /** Files (or directories) to optimize; may live outside the root. */ readonly inputs: readonly string[]; /** Output directory; defaults to each input's own directory. Resolved against the root. */ readonly outDir?: string; /** LDR texture dimension cap (default 2048). */ readonly maxDimension?: number; /** Equirect HDR dimension cap (default 4096); HDR inputs above it are refused, not resized. */ readonly hdrMaxDimension?: number; /** `high` upgrades color slots to UASTC and raises encoder effort. */ readonly quality?: 'default' | 'high'; /** Standalone-image preset override; GLB textures always classify by slot. */ readonly preset?: Exclude; /** Re-encode even when the cache already has this input + settings. */ readonly force?: boolean; readonly onProgress?: (message: string) => void; } interface TextureEncodeResult { readonly name: string; readonly slots: readonly string[]; readonly preset: TexturePreset; readonly mode: TextureEncodeMode; readonly width: number; readonly height: number; readonly bytesIn: number; readonly bytesOut: number; readonly durationMs: number; } interface OptimizedAssetResult { readonly input: string; readonly output: string; readonly kind: AssetKind; readonly cached: boolean; readonly bytesIn: number; readonly bytesOut: number; readonly vramBytesIn: number; readonly vramBytesOut: number; readonly textures: readonly TextureEncodeResult[]; readonly notes: readonly string[]; } interface FailedAssetResult { readonly input: string; readonly error: string; } interface AssetOptimizeReport { readonly schemaVersion: 1; readonly command: 'assets optimize'; readonly root: string; readonly results: readonly OptimizedAssetResult[]; readonly failed: readonly FailedAssetResult[]; readonly bytesIn: number; readonly bytesOut: number; } /** Classify a glTF texture by the material slots that reference it. */ declare function presetForTextureSlots(slots: readonly string[]): Exclude; /** Filename heuristic for standalone images; color is the safe default. */ declare function presetForImageName(fileName: string): Exclude; /** Optimize the given assets and commit the receipt last. */ declare function optimizeAssets(options: AssetOptimizeOptions): Promise; declare function formatAssetOptimizeReport(report: AssetOptimizeReport): string; /** * Project assets the capture step optimizes automatically: every `.glb` and * `.hdr` under the public directory, excluding generated output (the * `three-blocks/` subtree, `.tb.glb` rewrites) and hidden directories. * Standalone images stay opt-in โ€” a public directory legitimately holds * posters and favicons that must never become GPU textures. */ declare function discoverPublicAssets(root: string, publicDir: string): Promise; type AssetState = 'fresh' | 'stale' | 'missing-input' | 'missing-output'; interface AssetStatusEntry { readonly input: string; readonly output: string; readonly kind: AssetKind; readonly state: AssetState; } interface AssetStatusReport { readonly schemaVersion: 1; readonly command: 'assets status'; readonly root: string; readonly state: 'fresh' | 'stale' | 'empty'; readonly entries: readonly AssetStatusEntry[]; } /** Re-verify every receipt entry against the bytes on disk. */ declare function inspectAssets(root: string): Promise; declare function formatAssetStatusReport(report: AssetStatusReport): string; export { ASSET_OPTIMIZE_VERSION, ASSET_RECEIPT_DIRECTORY, ASSET_RECEIPT_FILE, type AdoptedProjectStatus, type ArtifactState, type AssetKind, type AssetOptimizeOptions, type AssetOptimizeReport, type AssetState, type AssetStatusEntry, type AssetStatusReport, type BrowserPreviewOptions, type BrowserPreviewReport, type BrowserPreviewRouteReport, type BrowserShaderCounters, type BrowserSmokeBuildReceipt, type BrowserSmokeCodec, type BrowserSmokeCodecRoute, type BrowserSmokeHmr, type BrowserSmokeHmrEvidence, type BrowserSmokeLifecycle, type BrowserSmokeOptions, type BrowserSmokeReport, type BrowserSmokeWorkerRestart, type BuiltinFontMetadata, type CaptureBuiltShadersOptions, type CaptureBuiltShadersResult, type CaptureSceneResult, type CaptureShadersOptions, type CaptureShadersResult, DOCUMENTED_BROWSER_NOISE, type DiscoveredTextContent, type EncodedRoomEnvironment, type EnsuredShaderToolConfig, type EnvironmentBakeOptions, type EnvironmentBakeReport, type FailedAssetResult, type GenerateTextResult, type GeneratedTextAtlas, type GlyphSet, type GlyphSetOptions, type InferredShaderCaptureTarget, type InstalledShaderRuntime, type OptimizedAssetResult, type ProjectCheckReport, 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 ShaderDriverOptions, 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, 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 TextureEncodeMode, type TextureEncodeResult, type TexturePreset, type ThreeBlocksStatus, type ToolTextConfiguration, type ToolTextFontRoute, type ToolTextFontSource, type ToolTextGenerationOptions, type ValidateShaderCaptureOptions, type ValidatedShaderCapture, type WriteShaderArtifactsOptions, type WrittenShaderArtifacts, bakeRoomEnvironment, buildGlyphSet, builtinFontMetadata, captureBuiltShaders, captureRoomEnvironment, captureShaders, compareShaderScreenshots, createShaderDriver, discoverPublicAssets, discoverTextContent, encodeRoomEnvironmentKtx2, ensureShaderToolConfig, extractCanvasTextFromHtml, extractDefinedTextContent, findProjectRoot, findShaderProjectRoot, formatAssetOptimizeReport, formatAssetStatusReport, formatBrowserPreviewReport, formatBrowserSmokeReport, formatEnvironmentBakeReport, formatProjectCheckReport, formatShaderMatrixStatus, formatStatus, formatThreeBlocksStatus, generateTextAtlases, inferShaderCaptureTarget, inspectAssets, inspectProject, inspectShaderMatrix, inspectTextAtlases, inspectThreeBlocksStatus, isDocumentedBrowserNoise, isRetryableShaderObservationNavigation, loadShaderCaptureRuntimeSource, loadShaderToolConfig, optimizeAssets, parseBrowserSmokeLifecycle, parseProjectMetadata, parseRuntimeStatusReceipt, parseShaderReceipt, parseShaderToolConfig, parseTextAtlasReceipt, parseTextConfiguration, presetForImageName, presetForTextureSlots, prewarmBuiltinFont, readInstalledShaderRuntime, readShaderCommittedTiming, readShaderLocalTiming, readShaderParityEvidence, readShaderTiming, readTextConfiguration, runBrowserPreview, runBrowserSmoke, runProjectCheck, screenshotLuminance, serializeShaderManifest, shaderCoverage, shaderScreenshotMetrics, snapshotShaderInputs, stableStringify, testShaders, threeBlocksStatusIsFresh, validateEnvironmentCubeSize, validateShaderCapture, webgpuBrowserArgs, webgpuBrowserHeadless, writeShaderArtifacts, writeShaderLocalTiming, writeShaderParityEvidence, writeShaderTimingTwins };