@flare-engine/postfx 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,317 @@
+/**
+ * Ordered post-processing pipeline. Pure data structure — the runtime reads
+ * the enabled entries in order and feeds each through its compiled shader.
+ */
+declare class EffectChain {
+    private _effects;
+    private _globalIntensity;
+    get length(): number;
+    /**
+     * Global intensity multiplier applied to every enabled effect's
+     * "strength" uniform when the pass is built. Default 1 (no-op).
+     *
+     * Scales the following uniform fields at pass-build time:
+     *  - vignette.intensity
+     *  - grayscale-flash.intensity
+     *  - chromatic-aberration.amount
+     *  - crt.scanlineIntensity
+     *  - bloom.intensity
+     *
+     * Geometry-like uniforms (radius, curvature, threshold) are not scaled.
+     * Intended for a11y reduced-motion (set to 0 to null all dampen-able
+     * effects in one call) without touching per-effect state.
+     *
+     * Clamped to `>= 0`. Negative values are clamped to 0.
+     */
+    get globalIntensity(): number;
+    set globalIntensity(value: number);
+    /** Convenience setter — mirrors the getter/setter. */
+    setGlobalIntensity(value: number): void;
+    /** Snapshot view of the chain. Do not mutate. */
+    all(): readonly Effect[];
+    /** Append an effect to the end of the chain. */
+    add(effect: Effect): void;
+    /** Insert an effect at a specific index (clamped to [0, length]). */
+    insert(index: number, effect: Effect): void;
+    remove(id: string): boolean;
+    get(id: string): Effect | null;
+    setEnabled(id: string, enabled: boolean): void;
+    /** Update uniforms in place. Kind must match the existing effect's kind. */
+    setUniforms(id: string, uniforms: EffectUniforms): void;
+    move(id: string, newIndex: number): void;
+    clear(): void;
+    /** Iterate only over enabled effects, in order. */
+    enabled(): IterableIterator<Effect>;
+}
+
+/**
+ * Runtime — compiles SkSL sources on demand, builds uniform buffers per effect,
+ * and exposes `buildPass` that the bridge calls to get pass descriptors for
+ * rendering. Rendering itself is owned by the bridge in `@flare-engine/react`.
+ */
+/**
+ * Structural stub for a Skia image handle. No Skia import is needed here
+ * because the renderer owns the actual image objects; this type exists only
+ * so callers can assign real `SkImage` values to `CompiledPass.children`
+ * without coupling this package to a specific Skia version.
+ */
+interface SkImageLike {
+    readonly _skImageBrand?: never;
+}
+interface SkiaRuntimeEffectLike {
+    makeShaderWithChildren(uniforms: number[], children?: unknown[]): unknown | null;
+    /** Optional diagnostic — total float count expected by makeShaderWithChildren. */
+    getUniformFloatCount?(): number;
+}
+interface SkiaRuntimeEffectFactory {
+    Make(sksl: string): SkiaRuntimeEffectLike | null;
+}
+interface SkiaPostFxModuleLike {
+    RuntimeEffect: SkiaRuntimeEffectFactory;
+}
+interface CompiledShader {
+    kind: EffectKind;
+    effect: SkiaRuntimeEffectLike;
+}
+interface PostFxRuntime {
+    /** True when the underlying Skia module reported a working RuntimeEffect. */
+    readonly supported: boolean;
+    /** Lazily compile (and cache) the shader for a given effect. Returns null on unsupported. */
+    compile(kind: EffectKind): CompiledShader | null;
+    /** Pack an effect's uniforms into a Float32Array in the order the shader declares. */
+    packUniforms(effect: Effect, width: number, height: number): Float32Array;
+    /** Build a list of compiled pass descriptors in chain order for enabled effects. */
+    buildPass(chain: EffectChain, width: number, height: number): CompiledPass[];
+    /** Drop all cached compiled shaders. */
+    reset(): void;
+}
+interface CompiledPass {
+    id: string;
+    kind: EffectKind;
+    shader: SkiaRuntimeEffectLike;
+    uniforms: Float32Array;
+    /**
+     * Convention A — extra sampler children only (excludes src).
+     *
+     * The renderer binds the implicit scene texture as `children[0]` at draw
+     * time. This array holds any *additional* `uniform shader` slots declared
+     * beyond `src` (e.g. a noise texture, an LUT). For every built-in effect
+     * today there are no extra children, so this is always the frozen
+     * `EMPTY_CHILDREN` sentinel — enabling zero-alloc sharing across passes.
+     */
+    children: readonly SkImageLike[];
+}
+/**
+ * Create a runtime against the given Skia-like module. If the module is
+ * absent or lacks `RuntimeEffect.Make`, returns a runtime with
+ * `supported: false` — callers should fall through to a passthrough pipeline.
+ */
+declare function createPostFxRuntime(skia: SkiaPostFxModuleLike | null): PostFxRuntime;
+
+/**
+ * Effect — an ordered entry in the post-processing chain.
+ *
+ * `kind` selects a bundled shader (see `shaders.ts`). Each effect owns its
+ * own uniform object; the runtime feeds these straight into the compiled
+ * RuntimeEffect at draw time.
+ */
+
+type EffectKind = 'vignette' | 'grayscale-flash' | 'chromatic-aberration' | 'crt' | 'bloom' | 'god-rays' | 'color-grading-lut' | 'weather-rain' | 'weather-sun-shaft' | 'weather-dark-vignette' | 'weather-clouds' | 'composite';
+interface VignetteUniforms {
+    intensity: number;
+    radius: number;
+    color?: readonly [number, number, number];
+}
+interface GrayscaleFlashUniforms {
+    intensity: number;
+}
+interface ChromaticAberrationUniforms {
+    amount: number;
+}
+interface CrtUniforms {
+    scanlineIntensity: number;
+    curvature: number;
+}
+interface BloomUniforms {
+    threshold: number;
+    intensity: number;
+}
+interface GodRaysUniforms {
+    lightX: number;
+    lightY: number;
+    color: readonly [number, number, number];
+    intensity: number;
+    decay: number;
+    density: number;
+    weight: number;
+    samples: number;
+}
+interface ColorGradingLutUniforms {
+    lut: SkImageLike;
+    intensity: number;
+}
+interface WeatherRainUniforms {
+    intensity: number;
+    direction: number;
+    speed: number;
+    scrollOffsetY: number;
+    color?: readonly [number, number, number];
+    density?: number;
+    streakLen?: number;
+}
+interface WeatherSunShaftUniforms {
+    intensity: number;
+    direction: number;
+}
+interface WeatherDarkVignetteUniforms {
+    intensity: number;
+}
+interface WeatherCloudsUniforms {
+    intensity: number;
+    direction: number;
+    speed: number;
+    scrollOffsetX: number;
+}
+interface CompositeUniforms {
+    vignetteIntensity: number;
+    vignetteRadius: number;
+    vignetteColor: readonly [number, number, number];
+    bloomThreshold: number;
+    bloomIntensity: number;
+    flashIntensity: number;
+    chromaAmount: number;
+    crtScanlineIntensity: number;
+    crtCurvature: number;
+    crtEnabled: boolean;
+    weatherKind: 0 | 1 | 2 | 3 | 4;
+    weatherIntensity: number;
+    weatherDirection: number;
+    weatherScrollX: number;
+    weatherScrollY: number;
+    weatherColor: readonly [number, number, number];
+    weatherDensity: number;
+    weatherStreakLen: number;
+}
+type EffectUniforms = ({
+    kind: 'vignette';
+} & VignetteUniforms) | ({
+    kind: 'grayscale-flash';
+} & GrayscaleFlashUniforms) | ({
+    kind: 'chromatic-aberration';
+} & ChromaticAberrationUniforms) | ({
+    kind: 'crt';
+} & CrtUniforms) | ({
+    kind: 'bloom';
+} & BloomUniforms) | ({
+    kind: 'god-rays';
+} & GodRaysUniforms) | ({
+    kind: 'color-grading-lut';
+} & ColorGradingLutUniforms) | ({
+    kind: 'weather-rain';
+} & WeatherRainUniforms) | ({
+    kind: 'weather-sun-shaft';
+} & WeatherSunShaftUniforms) | ({
+    kind: 'weather-dark-vignette';
+} & WeatherDarkVignetteUniforms) | ({
+    kind: 'weather-clouds';
+} & WeatherCloudsUniforms) | ({
+    kind: 'composite';
+} & CompositeUniforms);
+interface Effect {
+    id: string;
+    enabled: boolean;
+    uniforms: EffectUniforms;
+}
+declare function createVignette(id?: string, uniforms?: Partial<VignetteUniforms>): Effect;
+declare function createGrayscaleFlash(id?: string, uniforms?: Partial<GrayscaleFlashUniforms>): Effect;
+declare function createChromaticAberration(id?: string, uniforms?: Partial<ChromaticAberrationUniforms>): Effect;
+declare function createCrt(id?: string, uniforms?: Partial<CrtUniforms>): Effect;
+declare function createBloom(id?: string, uniforms?: Partial<BloomUniforms>): Effect;
+declare function createGodRays(id?: string, uniforms?: Partial<GodRaysUniforms>): Effect;
+declare function createColorGradingLut(uniforms: {
+    lut: SkImageLike;
+    intensity?: number;
+}, id?: string): Effect;
+declare function createWeatherRain(id?: string, uniforms?: Partial<WeatherRainUniforms>): Effect;
+declare function createWeatherSunShaft(id?: string, uniforms?: Partial<WeatherSunShaftUniforms>): Effect;
+declare function createWeatherDarkVignette(id?: string, uniforms?: Partial<WeatherDarkVignetteUniforms>): Effect;
+declare function createWeatherClouds(id?: string, uniforms?: Partial<WeatherCloudsUniforms>): Effect;
+declare function createPostFxComposite(id?: string, uniforms?: Partial<CompositeUniforms>): Effect;
+
+/**
+ * SkSL runtime-effect shaders used by the postfx stack.
+ *
+ * Each source declares a `uniform shader src;` plus per-effect uniforms. They
+ * are sampled as `src.eval(fragCoord)` against the scene's offscreen surface.
+ *
+ * Shader strings are emitted from the package as-is. Fallback: when
+ * `Skia.RuntimeEffect.Make` is unavailable, `runtime.ts` short-circuits the
+ * chain to a passthrough.
+ */
+declare const VIGNETTE_SKSL = "\nuniform shader src;\nuniform float2 resolution;\nuniform float intensity;\nuniform float radius;\nuniform float3 color;\n\nhalf4 main(float2 coord) {\n  half4 c = src.eval(coord);\n  float2 uv = coord / resolution;\n  float2 centered = uv - 0.5;\n  float d = length(centered);\n  float v = smoothstep(radius, radius * 0.5, d);\n  return half4(mix(half3(color), c.rgb, mix(1.0 - intensity, 1.0, v)), c.a);\n}\n";
+declare const GRAYSCALE_FLASH_SKSL = "\nuniform shader src;\nuniform float intensity;\n\nhalf4 main(float2 coord) {\n  half4 c = src.eval(coord);\n  float luma = dot(c.rgb, half3(0.299, 0.587, 0.114));\n  half3 gray = half3(luma);\n  half3 mixed = mix(c.rgb, gray, half(intensity));\n  return half4(mixed, c.a);\n}\n";
+declare const CHROMATIC_ABERRATION_SKSL = "\nuniform shader src;\nuniform float2 resolution;\nuniform float amount;\n\nhalf4 main(float2 coord) {\n  float2 uv = coord / resolution;\n  float2 offset = (uv - 0.5) * amount;\n  half r = src.eval((uv - offset) * resolution).r;\n  half g = src.eval(coord).g;\n  half b = src.eval((uv + offset) * resolution).b;\n  half a = src.eval(coord).a;\n  return half4(r, g, b, a);\n}\n";
+declare const CRT_SKSL = "\nuniform shader src;\nuniform float2 resolution;\nuniform float scanlineIntensity;\nuniform float curvature;\n\nhalf4 main(float2 coord) {\n  float2 uv = coord / resolution;\n  float2 centered = uv - 0.5;\n  float2 warp = centered * (1.0 + dot(centered, centered) * curvature);\n  float2 warpedUv = warp + 0.5;\n  if (warpedUv.x < 0.0 || warpedUv.x > 1.0 || warpedUv.y < 0.0 || warpedUv.y > 1.0) {\n    return half4(0.0, 0.0, 0.0, 1.0);\n  }\n  half4 c = src.eval(warpedUv * resolution);\n  float scan = 0.5 + 0.5 * sin(warpedUv.y * resolution.y * 3.14159);\n  float dim = mix(1.0, scan, scanlineIntensity);\n  return half4(c.rgb * dim, c.a);\n}\n";
+declare const BLOOM_SKSL = "\nuniform shader src;\nuniform float2 resolution;\nuniform float threshold;\nuniform float intensity;\n\nhalf4 main(float2 coord) {\n  half4 c = src.eval(coord);\n  float luma = dot(c.rgb, half3(0.299, 0.587, 0.114));\n  float mask = smoothstep(threshold, 1.0, luma);\n  half3 boost = c.rgb * mask * intensity;\n  return half4(c.rgb + boost, c.a);\n}\n";
+declare const COLOR_GRADING_LUT_SKSL = "\nuniform shader src;\nuniform shader lut;\nuniform float intensity;\n\nhalf4 main(float2 coord) {\n  half4 scene = src.eval(coord);\n\n  float r = float(scene.r) * 63.0;\n  float g = float(scene.g) * 63.0;\n  float b = float(scene.b) * 63.0;\n\n  float bFloor = floor(b);\n  float bCeil  = min(bFloor + 1.0, 63.0);\n  float bFrac  = b - bFloor;\n\n  float2 uvFloor = float2((bFloor * 64.0 + r + 0.5) / 4096.0,\n                          (g + 0.5) / 64.0);\n  float2 uvCeil  = float2((bCeil  * 64.0 + r + 0.5) / 4096.0,\n                          (g + 0.5) / 64.0);\n\n  half3 lutFloor = lut.eval(uvFloor * float2(4096.0, 64.0)).rgb;\n  half3 lutCeil  = lut.eval(uvCeil  * float2(4096.0, 64.0)).rgb;\n\n  half3 graded = mix(lutFloor, lutCeil, half(bFrac));\n  half3 result = mix(scene.rgb, graded, half(intensity));\n\n  return half4(result, scene.a);\n}\n";
+declare const WEATHER_RAIN_SKSL = "\nuniform shader src;\nuniform float2 resolution;\nuniform float intensity;\nuniform float direction;\nuniform float scrollOffsetY;\nuniform float3 color;\nuniform float density;\nuniform float streakLen;\n\n// scrollOffsetY is a normalized fall phase in [0,1). Increase it each tick\n// by (speed * dt / screenHeight) and wrap with fract() on the game side.\n\nfloat hash(float2 p) { return fract(sin(dot(p, float2(127.1, 311.7))) * 43758.5453); }\n\nhalf4 main(float2 coord) {\n  half4 scene = src.eval(coord);\n  float2 uv = coord / resolution;\n  float aspect = resolution.x / resolution.y;\n  float rad = direction * 3.14159 / 180.0;\n  float sinA = sin(rad);\n  float cosA = cos(rad);\n  // aspect-corrected rotated axes: fallAxis along drop travel, perpAxis across\n  float perpAxis = (cosA * uv.x - sinA * uv.y) * aspect;\n  float fallAxis = sinA * uv.x + cosA * uv.y;\n\n  float coverage = 0.0;\n\n  // near layer \u2014 COLS=45, tiling=6, brightness=1.0\n  {\n    float COLS = 45.0;\n    float tiling = 6.0;\n    float brightness = 1.0;\n    float cid = floor(perpAxis * COLS);\n    float colHash = hash(float2(cid, 0.0));\n    if (colHash < density) {\n      float phase = hash(float2(cid, 1.0));\n      float colBright = brightness * (0.6 + hash(float2(cid, 2.0)) * 0.4);\n      float center = 0.5 + (hash(float2(cid, 3.0)) - 0.5) * 0.4;\n      float seg = fract(fallAxis * tiling - scrollOffsetY + phase);\n      float coverageY = smoothstep(streakLen, 0.0, seg);\n      float width = 0.04;\n      float xMask = smoothstep(width, 0.0, abs(fract(perpAxis * COLS) - center));\n      coverage = max(coverage, coverageY * xMask * colBright);\n    }\n  }\n\n  // far layer \u2014 COLS=85, tiling=11, brightness=0.5\n  {\n    float COLS = 85.0;\n    float tiling = 11.0;\n    float brightness = 0.5;\n    float cid = floor(perpAxis * COLS);\n    float colHash = hash(float2(cid, 10.0));\n    if (colHash < density) {\n      float phase = hash(float2(cid, 11.0));\n      float colBright = brightness * (0.6 + hash(float2(cid, 12.0)) * 0.4);\n      float center = 0.5 + (hash(float2(cid, 13.0)) - 0.5) * 0.4;\n      float seg = fract(fallAxis * tiling - scrollOffsetY + phase);\n      float coverageY = smoothstep(streakLen, 0.0, seg);\n      float width = 0.03;\n      float xMask = smoothstep(width, 0.0, abs(fract(perpAxis * COLS) - center));\n      coverage = max(coverage, coverageY * xMask * colBright);\n    }\n  }\n\n  half3 mixed = mix(scene.rgb, half3(color), half(coverage * intensity));\n  return half4(mixed, scene.a);\n}\n";
+declare const WEATHER_SUN_SHAFT_SKSL = "\nuniform shader src;\nuniform float2 resolution;\nuniform float intensity;\nuniform float direction;\n\nhalf4 main(float2 coord) {\n  half4 scene = src.eval(coord);\n  float2 uv = coord / resolution;\n  float rad = direction * 3.14159 / 180.0;\n  float2 src_point = float2(0.5 + sin(rad) * 0.3, -0.05);\n  float2 toFrag = uv - src_point;\n  float angle = atan(toFrag.x, toFrag.y);\n  float shafts = 0.5 + 0.5 * sin(angle * 8.0);\n  float dist = length(toFrag);\n  float falloff = 1.0 - smoothstep(0.0, 1.2, dist);\n  half shaft = half(shafts * falloff * intensity * 0.35);\n  return half4(scene.rgb + half3(shaft * 0.95, shaft * 0.9, shaft * 0.6), scene.a);\n}\n";
+declare const WEATHER_DARK_VIGNETTE_SKSL = "\nuniform shader src;\nuniform float2 resolution;\nuniform float intensity;\n\nhalf4 main(float2 coord) {\n  half4 scene = src.eval(coord);\n  float2 uv = coord / resolution - 0.5;\n  float d = length(uv);\n  float v = smoothstep(0.3, 0.85, d);\n  half dark = half(v * intensity);\n  return half4(scene.rgb * (1.0 - dark), scene.a);\n}\n";
+declare const WEATHER_CLOUDS_SKSL = "\nuniform shader src;\nuniform float2 resolution;\nuniform float intensity;\nuniform float scrollOffsetX;\n\nfloat hash(float2 p) { return fract(sin(dot(p, float2(127.1, 311.7))) * 43758.5453); }\nfloat vnoise(float2 p) {\n  float2 i = floor(p); float2 f = fract(p);\n  float2 u = f * f * (3.0 - 2.0 * f);\n  return mix(mix(hash(i), hash(i + float2(1.0, 0.0)), u.x),\n             mix(hash(i + float2(0.0, 1.0)), hash(i + float2(1.0, 1.0)), u.x), u.y);\n}\nfloat fbm(float2 p) { return vnoise(p) * 0.6 + vnoise(p * 2.3) * 0.4; }\n\nhalf4 main(float2 coord) {\n  half4 scene = src.eval(coord);\n  float2 uv = coord / resolution;\n  float2 cloudUv = float2(uv.x + scrollOffsetX / resolution.x, uv.y * 0.5);\n  float cloud = fbm(cloudUv * 3.0);\n  float heightFade = smoothstep(0.6, 0.2, uv.y);\n  float alpha = cloud * heightFade * intensity * 0.5;\n  half3 cloudColor = half3(0.9, 0.9, 0.95);\n  return half4(mix(scene.rgb, cloudColor, half(alpha)), scene.a);\n}\n";
+declare const COMPOSITE_SKSL = "\nuniform shader src;\n\nuniform float2 resolution;\nuniform float vignetteIntensity;\nuniform float vignetteRadius;\nuniform float3 vignetteColor;\nuniform float bloomThreshold;\nuniform float bloomIntensity;\nuniform float flashIntensity;\nuniform float chromaAmount;\nuniform float crtScanlineIntensity;\nuniform float crtCurvature;\nuniform float crtEnabled;\nuniform float weatherKind;\nuniform float weatherIntensity;\nuniform float weatherDirection;\nuniform float weatherScrollX;\nuniform float weatherScrollY;\nuniform float3 weatherColor;\nuniform float weatherDensity;\nuniform float weatherStreakLen;\n\nfloat hash(float2 p) { return fract(sin(dot(p, float2(127.1, 311.7))) * 43758.5453); }\nfloat vnoise(float2 p) {\n  float2 i = floor(p); float2 f = fract(p);\n  float2 u = f * f * (3.0 - 2.0 * f);\n  return mix(mix(hash(i), hash(i + float2(1.0, 0.0)), u.x),\n             mix(hash(i + float2(0.0, 1.0)), hash(i + float2(1.0, 1.0)), u.x), u.y);\n}\nfloat fbm(float2 p) { return vnoise(p) * 0.6 + vnoise(p * 2.3) * 0.4; }\n\nhalf4 main(float2 coord) {\n  // --- chromatic aberration ---\n  float2 uv = coord / resolution;\n  float2 chromaOffset = (uv - 0.5) * chromaAmount;\n  half r = src.eval((uv - chromaOffset) * resolution).r;\n  half g = src.eval(coord).g;\n  half b = src.eval((uv + chromaOffset) * resolution).b;\n  half3 c = half3(r, g, b);\n\n  // --- CRT ---\n  float2 crtCentered = uv - 0.5;\n  float2 crtWarp = crtCentered * (1.0 + dot(crtCentered, crtCentered) * crtCurvature);\n  float2 crtUv = crtWarp + 0.5;\n  float crtMask = float(crtUv.x >= 0.0 && crtUv.x <= 1.0 && crtUv.y >= 0.0 && crtUv.y <= 1.0);\n  {\n    float2 chromaOffsetCrt = (crtUv - 0.5) * chromaAmount;\n    half rCrt = src.eval((crtUv - chromaOffsetCrt) * resolution).r;\n    half gCrt = src.eval(crtUv * resolution).g;\n    half bCrt = src.eval((crtUv + chromaOffsetCrt) * resolution).b;\n    half3 crtColor = half3(rCrt, gCrt, bCrt);\n    float scan = 0.5 + 0.5 * sin(crtUv.y * resolution.y * 3.14159);\n    float dim = mix(1.0, scan, crtScanlineIntensity);\n    half3 crtResult = crtColor * half(dim);\n    c = mix(c, mix(half3(0.0), crtResult, half(crtMask)), half(crtEnabled));\n  }\n\n  // --- bloom ---\n  float luma = dot(c, half3(0.299, 0.587, 0.114));\n  float bloomMask = smoothstep(bloomThreshold, 1.0, luma);\n  c = c + c * half(bloomMask * bloomIntensity);\n\n  // --- weather ---\n  {\n    float wk = weatherKind;\n    if (wk >= 0.5 && wk < 1.5) {\n      // rain \u2014 falling sawtooth streaks, 2 parallax layers, alpha-over blend\n      // weatherScrollY is normalized [0,1) fall phase (increment speed*dt/screenH each tick)\n      float rad = weatherDirection * 3.14159 / 180.0;\n      float sinA = sin(rad);\n      float cosA = cos(rad);\n      float aspect = resolution.x / resolution.y;\n      float perpAxis = (cosA * uv.x - sinA * uv.y) * aspect;\n      float fallAxis = sinA * uv.x + cosA * uv.y;\n\n      float coverage = 0.0;\n\n      // near layer \u2014 COLS=45, tiling=6, brightness=1.0\n      {\n        float COLS = 45.0;\n        float tiling = 6.0;\n        float brightness = 1.0;\n        float cid = floor(perpAxis * COLS);\n        float colHash = hash(float2(cid, 0.0));\n        if (colHash < weatherDensity) {\n          float phase = hash(float2(cid, 1.0));\n          float colBright = brightness * (0.6 + hash(float2(cid, 2.0)) * 0.4);\n          float center = 0.5 + (hash(float2(cid, 3.0)) - 0.5) * 0.4;\n          float seg = fract(fallAxis * tiling - weatherScrollY + phase);\n          float coverageY = smoothstep(weatherStreakLen, 0.0, seg);\n          float width = 0.04;\n          float xMask = smoothstep(width, 0.0, abs(fract(perpAxis * COLS) - center));\n          coverage = max(coverage, coverageY * xMask * colBright);\n        }\n      }\n\n      // far layer \u2014 COLS=85, tiling=11, brightness=0.5\n      {\n        float COLS = 85.0;\n        float tiling = 11.0;\n        float brightness = 0.5;\n        float cid = floor(perpAxis * COLS);\n        float colHash = hash(float2(cid, 10.0));\n        if (colHash < weatherDensity) {\n          float phase = hash(float2(cid, 11.0));\n          float colBright = brightness * (0.6 + hash(float2(cid, 12.0)) * 0.4);\n          float center = 0.5 + (hash(float2(cid, 13.0)) - 0.5) * 0.4;\n          float seg = fract(fallAxis * tiling - weatherScrollY + phase);\n          float coverageY = smoothstep(weatherStreakLen, 0.0, seg);\n          float width = 0.03;\n          float xMask = smoothstep(width, 0.0, abs(fract(perpAxis * COLS) - center));\n          coverage = max(coverage, coverageY * xMask * colBright);\n        }\n      }\n\n      c = mix(c, half3(weatherColor), half(coverage * weatherIntensity));\n    } else if (wk >= 1.5 && wk < 2.5) {\n      // sun-shaft\n      float rad = weatherDirection * 3.14159 / 180.0;\n      float2 srcPoint = float2(0.5 + sin(rad) * 0.3, -0.05);\n      float2 toFrag = uv - srcPoint;\n      float angle = atan(toFrag.x, toFrag.y);\n      float shafts = 0.5 + 0.5 * sin(angle * 8.0);\n      float dist = length(toFrag);\n      float falloff = 1.0 - smoothstep(0.0, 1.2, dist);\n      half shaft = half(shafts * falloff * weatherIntensity * 0.35);\n      c = c + half3(shaft * 0.95, shaft * 0.9, shaft * 0.6);\n    } else if (wk >= 2.5 && wk < 3.5) {\n      // dark-vignette\n      float2 uvShift = uv - 0.5;\n      float d2 = length(uvShift);\n      float vd = smoothstep(0.3, 0.85, d2);\n      half dark = half(vd * weatherIntensity);\n      c = c * (1.0 - dark);\n    } else if (wk >= 3.5) {\n      // clouds\n      float2 cloudUv = float2(uv.x + weatherScrollX / resolution.x, uv.y * 0.5);\n      float cloud = fbm(cloudUv * 3.0);\n      float heightFade = smoothstep(0.6, 0.2, uv.y);\n      float alpha = cloud * heightFade * weatherIntensity * 0.5;\n      half3 cloudColor = half3(0.9, 0.9, 0.95);\n      c = mix(c, cloudColor, half(alpha));\n    }\n  }\n\n  // --- grayscale flash ---\n  float lumaFlash = dot(c, half3(0.299, 0.587, 0.114));\n  half3 gray = half3(lumaFlash);\n  c = mix(c, gray, half(flashIntensity));\n\n  // --- vignette ---\n  float2 vigCentered = uv - 0.5;\n  float vigD = length(vigCentered);\n  float vigV = smoothstep(vignetteRadius, vignetteRadius * 0.5, vigD);\n  c = mix(half3(vignetteColor), c, half(mix(1.0 - vignetteIntensity, 1.0, vigV)));\n\n  return half4(c, 1.0);\n}\n";
+declare const GOD_RAYS_SKSL = "\nuniform shader src;\nuniform float2 resolution;\nuniform float2 u_lightPos;\nuniform float3 u_color;\nuniform float u_intensity;\nuniform float u_decay;\nuniform float u_density;\nuniform float u_weight;\nuniform float u_samples;\n\nconst int MAX_SAMPLES = 64;\n\nhalf4 main(float2 coord) {\n  float2 uv = coord / resolution;\n  float2 delta = (u_lightPos - uv) * u_density / float(MAX_SAMPLES);\n  float2 sampleUv = uv;\n  float illuminationDecay = 1.0;\n  half3 accumulated = half3(0.0);\n\n  for (int i = 0; i < MAX_SAMPLES; i++) {\n    if (float(i) >= u_samples) break;\n    sampleUv += delta;\n    half3 s = src.eval(sampleUv * resolution).rgb;\n    accumulated += s * half(illuminationDecay) * half(u_weight);\n    illuminationDecay *= u_decay;\n  }\n\n  half4 orig = src.eval(coord);\n  half3 rays = accumulated * half3(u_color) * half(u_weight) * half(u_intensity);\n  return half4(orig.rgb + rays, orig.a);\n}\n";
+
+declare function createNeutralLutBytes(): Uint8Array;
+
+/**
+ * PostFxController — a small bridge that owns an EffectChain + PostFxRuntime
+ * and adds two game-common conveniences:
+ *
+ *   - hit-flash: spike a grayscale-flash effect to 1 and auto-decay it.
+ *   - motion scale: forward a single scalar to `EffectChain.setGlobalIntensity`
+ *     so a11y reduced-motion can null the whole stack at once.
+ *
+ * Extracted from Pan Tvardowski per Phase 11.14. Shape-compatible with the
+ * PT `createPanTvardowskiPostFx` controller — games can swap implementations.
+ */
+
+interface PostFxFlashConfig {
+    /** Id of a `grayscale-flash` effect already added to the chain. */
+    readonly id: string;
+    /** Decay rate in intensity units per second. Defaults to 4.2 (≈0.24 s to fade from 1). */
+    readonly decay?: number;
+}
+interface PostFxControllerOptions {
+    /** Effects appended to the internal chain in the given order. */
+    readonly effects: readonly Effect[];
+    /** Skia module — `null` / `undefined` keeps `buildPass` returning `[]`. */
+    readonly skia?: SkiaPostFxModuleLike | null;
+    /** Optional hit-flash binding. */
+    readonly flash?: PostFxFlashConfig;
+}
+interface PostFxController {
+    readonly chain: EffectChain;
+    readonly runtime: PostFxRuntime;
+    /** Spike the configured flash effect to 1. No-op if no flash configured. */
+    triggerHitFlash(): void;
+    /**
+     * Enable `effectId` immediately and auto-disable it after `decayMs` ms of
+     * accumulated `update(dt)` time. Uniforms are restored to the pre-trigger
+     * snapshot on expiry. Re-triggering before expiry resets the countdown.
+     * No-op if `effectId` is not in the chain.
+     */
+    /** Optional pending PT wire-up in session #196. */
+    triggerTimed?(effectId: string, decayMs: number): void;
+    /** Advance auto-decaying effects (flash + timed triggers). */
+    update(dt: number): void;
+    /** Build the per-frame compiled pass list. Empty if runtime is unsupported. */
+    buildPass(width: number, height: number): readonly CompiledPass[];
+    /**
+     * Global intensity multiplier forwarded to the chain — intended for a11y
+     * reduced-motion (0 = fully neutralized, 1 = default).
+     */
+    setMotionScale(k: number): void;
+}
+declare function createPostFxController(options: PostFxControllerOptions): PostFxController;
+
+export { BLOOM_SKSL, type BloomUniforms, CHROMATIC_ABERRATION_SKSL, COLOR_GRADING_LUT_SKSL, COMPOSITE_SKSL, CRT_SKSL, type ChromaticAberrationUniforms, type ColorGradingLutUniforms, type CompiledPass, type CompiledShader, type CompositeUniforms, type CrtUniforms, type Effect, EffectChain, type EffectKind, type EffectUniforms, GOD_RAYS_SKSL, GRAYSCALE_FLASH_SKSL, type GodRaysUniforms, type GrayscaleFlashUniforms, type PostFxController, type PostFxControllerOptions, type PostFxFlashConfig, type PostFxRuntime, type SkImageLike, type SkiaPostFxModuleLike, type SkiaRuntimeEffectFactory, type SkiaRuntimeEffectLike, VIGNETTE_SKSL, type VignetteUniforms, WEATHER_CLOUDS_SKSL, WEATHER_DARK_VIGNETTE_SKSL, WEATHER_RAIN_SKSL, WEATHER_SUN_SHAFT_SKSL, type WeatherCloudsUniforms, type WeatherDarkVignetteUniforms, type WeatherRainUniforms, type WeatherSunShaftUniforms, createBloom, createChromaticAberration, createColorGradingLut, createCrt, createGodRays, createGrayscaleFlash, createNeutralLutBytes, createPostFxComposite, createPostFxController, createPostFxRuntime, createVignette, createWeatherClouds, createWeatherDarkVignette, createWeatherRain, createWeatherSunShaft };