@flare-engine/render 0.1.0 → 0.2.0

package/README.md

@@ -25,7 +25,7 @@ batch.flush(skia.drawAtlas, renderer);
 renderer.end();
 ```
 
-See [API spec](../../docs/design/api-specs.md#flare-enginerender--10kb-gzip) and [skill reference](../../.github/skills/flare-render/SKILL.md).
+See [API spec](../../docs/design/api-specs.md#flare-enginerender--10kb-gzip).
 
 ## License
 

package/dist/index.d.mts

@@ -233,6 +233,23 @@ interface FireEffect extends SpriteEffect {
     readonly speed: number;
     readonly intensity: number;
 }
+/**
+ * Drop-shadow effect — a single offset, blurred, tinted copy of the sprite drawn
+ * beneath it for ship / boss grounding. Time-invariant. Applied via a Skia
+ * `ImageFilter.MakeDropShadow` on a reused paint (sprite + shadow in one pass);
+ * the offset, blur, and tint all live in the filter, so no extra draw pass.
+ */
+interface DropShadowEffect extends SpriteEffect {
+    readonly type: 'drop-shadow';
+    /** Horizontal shadow offset in design px. */
+    readonly offsetX: number;
+    /** Vertical shadow offset in design px; positive = downward (grounding). */
+    readonly offsetY: number;
+    /** Gaussian blur sigma applied to the shadow. 0 = hard edge. */
+    readonly blur: number;
+    /** Shadow color; `a` is the shadow opacity. */
+    readonly color: SpriteColor;
+}
 /** Rooftop city skyline — AABB silhouettes via SDF hash fields. */
 interface RoofsCityEffect extends SpriteEffect {
     readonly type: 'roofs-city';
@@ -296,7 +313,7 @@ interface MountainHillsEffect extends SpriteEffect {
     readonly resolutionH: number;
 }
 /** Any concrete sprite effect. */
-type AnySpriteEffect = TintEffect | FlashEffect | GrayscaleEffect | OutlineEffect | CustomShaderEffect | WaterEffect | FogEffect | FireEffect | RoofsCityEffect | ForestCanopyEffect | RiverWaveEffect | MoonCraterEffect | CaveInteriorEffect | MountainHillsEffect;
+type AnySpriteEffect = TintEffect | FlashEffect | GrayscaleEffect | OutlineEffect | CustomShaderEffect | WaterEffect | FogEffect | FireEffect | DropShadowEffect | RoofsCityEffect | ForestCanopyEffect | RiverWaveEffect | MoonCraterEffect | CaveInteriorEffect | MountainHillsEffect;
 /** Create a tint effect. */
 declare function tint(color: SpriteColor, amount: number): TintEffect;
 /** Create a flash effect. */
@@ -323,6 +340,14 @@ declare function fire(opts: {
     speed?: number;
     intensity?: number;
 }): FireEffect;
+/** Create a drop-shadow effect. Defaults to a soft shadow offset downward for
+ *  grounding; `color.a` is the shadow opacity. */
+declare function dropShadow(opts: {
+    color: SpriteColor;
+    offsetX?: number;
+    offsetY?: number;
+    blur?: number;
+}): DropShadowEffect;
 /** Create a rooftop city skyline effect. */
 declare function roofsCity(opts: {
     skyColor: SpriteColor;
@@ -495,6 +520,169 @@ declare const MOON_CRATER_SKSL = "\nuniform float2 resolution;\nuniform float3 m
 declare const CAVE_INTERIOR_SKSL = "\nuniform float2 resolution;\nuniform float3 caveColor;\nuniform float3 glowColor;\nuniform float scrollOffsetY;\nuniform float stalactiteCount;\n\nfloat hash(float x) { return fract(sin(x * 127.1) * 43758.5453); }\n\nfloat stalactite(float2 uv, float count) {\n  float col = floor(uv.x * count);\n  float tip = 0.1 + 0.2 * hash(col);\n  float w = 0.3 + 0.3 * hash(col + 5.0);\n  float dx = abs(fract(uv.x * count) - 0.5) / (w * 0.5);\n  float shape = step(dx, 1.0) * step(uv.y, tip * (1.0 - clamp(dx, 0.0, 1.0)));\n  return shape;\n}\n\nhalf4 main(float2 coord) {\n  float2 uv = coord / max(resolution, float2(1.0));\n  uv.y = 1.0 - uv.y;\n  uv.y = uv.y + scrollOffsetY / max(resolution.y, 1.0);\n  float stalac = stalactite(uv, stalactiteCount);\n  float glow = smoothstep(0.8, 1.0, uv.y) * (1.0 - stalac);\n  half3 col = mix(half3(caveColor.r, caveColor.g, caveColor.b),\n                  half3(glowColor.r, glowColor.g, glowColor.b),\n                  half(glow));\n  col = mix(col, half3(caveColor.r, caveColor.g, caveColor.b) * half(0.3), half(stalac));\n  return half4(col, 1.0);\n}\n";
 declare const MOUNTAIN_HILLS_SKSL = "\nuniform float2 resolution;\nuniform float3 skyColor;\nuniform float3 hillColor;\nuniform float scrollOffsetY;\nuniform float ridgeScale;\n\nfloat hash(float x) { return fract(sin(x * 127.1) * 43758.5453); }\n\nfloat heightField(float x, float scale) {\n  float h = 0.0;\n  float amp = 0.5;\n  float freq = scale;\n  for (int i = 0; i < 4; i++) {\n    float ix = floor(x * freq);\n    float fx = fract(x * freq);\n    fx = fx * fx * (3.0 - 2.0 * fx);\n    h += amp * mix(hash(ix), hash(ix + 1.0), fx);\n    freq *= 2.0;\n    amp *= 0.5;\n  }\n  return h;\n}\n\nhalf4 main(float2 coord) {\n  float2 uv = coord / max(resolution, float2(1.0));\n  float scroll = scrollOffsetY / max(resolution.y, 1.0);\n  float horizon = 0.4 + 0.3 * heightField(uv.x + scroll * 0.3, ridgeScale);\n  float mountains = step(uv.y, horizon);\n  half3 col = mix(half3(skyColor.r, skyColor.g, skyColor.b),\n                  half3(hillColor.r, hillColor.g, hillColor.b),\n                  half(mountains));\n  return half4(col, 1.0);\n}\n";
 
+/** A 4-float RGBA color buffer (r, g, b, a in [0, 1]). */
+type ColorLike = Float32Array;
+/**
+ * A mutable axis-aligned rect.
+ *
+ * The `x`, `y`, `width`, `height` fields are required so that RN-Skia's
+ * `SkHostRect` (which carries those fields) structurally satisfies this
+ * interface in contra-variant parameter positions.
+ */
+interface RectLike {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    setXYWH(x: number, y: number, w: number, h: number): void;
+}
+/**
+ * A mutable similarity transform.
+ *
+ * The `scos`, `ssin`, `tx`, `ty` fields are readable so that CK-backed
+ * canvas wrappers can flatten pools into Float32Arrays without allocation.
+ * RN-Skia's `SkRSXform` exposes all four fields.
+ */
+interface RSXformLike {
+    scos: number;
+    ssin: number;
+    tx: number;
+    ty: number;
+    set(scos: number, ssin: number, tx: number, ty: number): void;
+}
+/** A compiled SkSL runtime effect. */
+interface RuntimeEffectLike {
+    makeShader(uniforms: number[]): unknown;
+    getUniformCount(): number;
+    getUniformFloatCount(): number;
+    getUniformName(index: number): string;
+    getUniform(index: number): {
+        columns: number;
+        rows: number;
+        slot: number;
+    };
+}
+/** Color filter factory — subset used by the frame-renderer. */
+interface ColorFilterFactoryLike {
+    MakeBlend(color: Float32Array, mode: number): unknown;
+    MakeMatrix(matrix: number[]): unknown;
+}
+/** Image filter factory — optional; absent on CPU/test surfaces. */
+interface ImageFilterFactoryLike {
+    MakeDropShadow(dx: number, dy: number, sigmaX: number, sigmaY: number, color: Float32Array, input: null): unknown;
+}
+/** Runtime-effect factory — optional; absent when SkSL is unsupported. */
+interface RuntimeEffectFactoryLike {
+    Make(sksl: string): RuntimeEffectLike | null;
+}
+/** Paint — the writable subset the frame-renderer mutates. */
+interface PaintLike {
+    setAlphaf(alpha: number): void;
+    setColor?(color: Float32Array): void;
+    setColorFilter(filter: unknown): void;
+    setShader(shader: unknown): void;
+    setImageFilter(filter: unknown): void;
+}
+/** Minimal draw surface the frame-renderer calls into. */
+interface DrawSurfaceLike {
+    save(): number;
+    restore(): void;
+    translate(x: number, y: number): void;
+    scale(sx: number, sy: number): void;
+    /** rotate(radians, cx, cy) — always in radians. Web shims must convert. */
+    rotate(radians: number, cx: number, cy: number): void;
+    clear(color: Float32Array): void;
+    drawAtlas(image: unknown, srcRects: RectLike[], dstXforms: RSXformLike[], paint: PaintLike): void;
+    drawImageRect(image: unknown, src: RectLike, dst: RectLike, paint: PaintLike): void;
+    drawRect(rect: RectLike, paint: PaintLike): void;
+}
+/**
+ * Opaque picture (recorded draw commands).
+ * Typed as `object` so both `SkPicture` (RN-Skia) and CanvasKit's
+ * `SkPicture` satisfy it without structural mismatches.
+ * Callers that need concrete type methods cast to the platform type.
+ */
+type PictureLike = object;
+/** Picture recorder. */
+interface PictureRecorderLike {
+    beginRecording(bounds: RectLike): DrawSurfaceLike;
+    finishRecordingAsPicture(): PictureLike;
+}
+/**
+ * Minimal structural view of the Skia module the frame-renderer needs.
+ * Declared here so both `@flare-engine/react` and `@flare-engine/render-web`
+ * can pass their respective backends without coupling to a concrete Skia SDK.
+ *
+ * The `Surface` and `ImageFilter` slots are optional because they are absent
+ * on CPU surfaces and in test mocks.
+ */
+interface FrameRendererModule {
+    XYWHRect(x: number, y: number, w: number, h: number): RectLike;
+    RSXform(scos: number, ssin: number, tx: number, ty: number): RSXformLike;
+    Paint(): PaintLike;
+    PictureRecorder(): PictureRecorderLike;
+    ColorFilter: ColorFilterFactoryLike;
+    RuntimeEffect?: RuntimeEffectFactoryLike;
+    ImageFilter?: ImageFilterFactoryLike;
+}
+/**
+ * A single compiled postfx pass descriptor produced by the runtime.
+ */
+interface FrameRendererCompiledPass {
+    readonly id: string;
+    readonly shader: {
+        makeShaderWithChildren(uniforms: number[], children: unknown[]): unknown | null;
+        getUniformCount?(): number;
+        getUniformName?(index: number): string;
+        getUniform?(index: number): {
+            columns: number;
+            rows: number;
+            slot: number;
+        };
+    };
+    readonly uniforms: Float32Array;
+    readonly children: readonly unknown[];
+}
+/** Minimal structural view of a PostFxRuntime that the frame-renderer needs. */
+interface FrameRendererPostFxRuntime {
+    readonly supported: boolean;
+    buildPass?(chain: FrameRendererPostFxChain, width: number, height: number): readonly FrameRendererCompiledPass[];
+}
+/** Minimal structural view of an EffectChain the frame-renderer needs. */
+interface FrameRendererPostFxChain {
+    enabled(): Iterable<unknown>;
+}
+/** A resolved postfx pass descriptor with named uniforms (for React JSX). */
+interface FrameRendererPostFxDescriptor {
+    readonly id: string;
+    readonly source: unknown;
+    readonly uniforms: Record<string, number | readonly number[]>;
+    readonly children: readonly unknown[];
+}
+/**
+ * Frame renderer that bridges a `SpriteBatch` to a picture-backed draw surface.
+ *
+ * Each frame:
+ *   1. Call `beginFrame(viewportWidth, viewportHeight)`.
+ *   2. Call `drawAtlas(image, commands)` one or more times.
+ *   3. Call `endFrame()` — returns the recorded picture.
+ */
+interface FrameRenderer {
+    readonly canvas: CanvasLike;
+    beginFrame(viewportWidth: number, viewportHeight: number, time?: number, pixelDensity?: number): void;
+    drawAtlas(image: SkImageLike, commands: SpriteDrawCommand[]): void;
+    buildPostFxPasses(runtime: FrameRendererPostFxRuntime | null, chain: FrameRendererPostFxChain | null, width: number, height: number): readonly FrameRendererPostFxDescriptor[];
+    setPostFxBinding(runtime: FrameRendererPostFxRuntime | null, chain: FrameRendererPostFxChain | null): void;
+    endFrame(): PictureLike | null;
+}
+/**
+ * Create a `FrameRenderer` backed by the given structural Skia module.
+ *
+ * Both `@flare-engine/react` (passing the real RN-Skia module) and
+ * `@flare-engine/render-web` (passing a CanvasKit shim) use this factory.
+ */
+declare function createFrameRenderer(Skia: FrameRendererModule): FrameRenderer;
+
 /** A single glyph in a bitmap font. */
 interface Glyph {
     /** Character code (Unicode). */
@@ -609,4 +797,4 @@ declare function createRenderSystem(world: World, query: Query, positionDef: Com
 /** Canonical Sprite component — queried by the render system alongside `Position`. */
 declare const Sprite: ComponentDef<SpriteData>;
 
-export { type AnySpriteEffect, type BitmapFont, CAVE_INTERIOR_SKSL, Camera2D, type CanvasLike, type CaveInteriorEffect, type CompiledShader, type CustomShaderEffect, type Drawable, FIRE_SKSL, FOG_SKSL, FOREST_CANOPY_SKSL, type FireEffect, type FlashEffect, type FogEffect, type FollowOptions, type ForestCanopyEffect, type Glyph, type GrayscaleEffect, type KerningPair, MOON_CRATER_SKSL, MOUNTAIN_HILLS_SKSL, type MoonCraterEffect, type MountainHillsEffect, type OutlineEffect, type PositionData, RIVER_WAVE_SKSL, ROOFS_CITY_SKSL, type RenderStats, Renderer, type RiverWaveEffect, type RoofsCityEffect, type ShaderUniforms, Sprite, type SpriteAnchor, SpriteBatch, type SpriteColor, type SpriteData, type SpriteDrawCommand, type SpriteEffect, type TintEffect, WATER_SKSL, type WaterEffect, caveInterior, createRenderSystem, custom, drawOrderCompare, drawText, fire, flash, flashIntensity, fog, forestCanopy, getKerning, grayscale, measureText, moonCrater, mountainHills, outline, parseBMFontJSON, riverWave, roofsCity, sortByDrawOrder, tint, updateEffect, water };
+export { type AnySpriteEffect, type BitmapFont, CAVE_INTERIOR_SKSL, Camera2D, type CanvasLike, type CaveInteriorEffect, type ColorFilterFactoryLike, type ColorLike, type CompiledShader, type CustomShaderEffect, type DrawSurfaceLike, type Drawable, type DropShadowEffect, FIRE_SKSL, FOG_SKSL, FOREST_CANOPY_SKSL, type FireEffect, type FlashEffect, type FogEffect, type FollowOptions, type ForestCanopyEffect, type FrameRenderer, type FrameRendererCompiledPass, type FrameRendererModule, type FrameRendererPostFxChain, type FrameRendererPostFxDescriptor, type FrameRendererPostFxRuntime, type Glyph, type GrayscaleEffect, type ImageFilterFactoryLike, type KerningPair, MOON_CRATER_SKSL, MOUNTAIN_HILLS_SKSL, type MoonCraterEffect, type MountainHillsEffect, type OutlineEffect, type PaintLike, type PictureLike, type PictureRecorderLike, type PositionData, RIVER_WAVE_SKSL, ROOFS_CITY_SKSL, type RSXformLike, type RectLike, type RenderStats, Renderer, type RiverWaveEffect, type RoofsCityEffect, type RuntimeEffectFactoryLike, type RuntimeEffectLike, type ShaderUniforms, Sprite, type SpriteAnchor, SpriteBatch, type SpriteColor, type SpriteData, type SpriteDrawCommand, type SpriteEffect, type TintEffect, WATER_SKSL, type WaterEffect, caveInterior, createFrameRenderer, createRenderSystem, custom, drawOrderCompare, drawText, dropShadow, fire, flash, flashIntensity, fog, forestCanopy, getKerning, grayscale, measureText, moonCrater, mountainHills, outline, parseBMFontJSON, riverWave, roofsCity, sortByDrawOrder, tint, updateEffect, water };

package/dist/index.d.ts

@@ -233,6 +233,23 @@ interface FireEffect extends SpriteEffect {
     readonly speed: number;
     readonly intensity: number;
 }
+/**
+ * Drop-shadow effect — a single offset, blurred, tinted copy of the sprite drawn
+ * beneath it for ship / boss grounding. Time-invariant. Applied via a Skia
+ * `ImageFilter.MakeDropShadow` on a reused paint (sprite + shadow in one pass);
+ * the offset, blur, and tint all live in the filter, so no extra draw pass.
+ */
+interface DropShadowEffect extends SpriteEffect {
+    readonly type: 'drop-shadow';
+    /** Horizontal shadow offset in design px. */
+    readonly offsetX: number;
+    /** Vertical shadow offset in design px; positive = downward (grounding). */
+    readonly offsetY: number;
+    /** Gaussian blur sigma applied to the shadow. 0 = hard edge. */
+    readonly blur: number;
+    /** Shadow color; `a` is the shadow opacity. */
+    readonly color: SpriteColor;
+}
 /** Rooftop city skyline — AABB silhouettes via SDF hash fields. */
 interface RoofsCityEffect extends SpriteEffect {
     readonly type: 'roofs-city';
@@ -296,7 +313,7 @@ interface MountainHillsEffect extends SpriteEffect {
     readonly resolutionH: number;
 }
 /** Any concrete sprite effect. */
-type AnySpriteEffect = TintEffect | FlashEffect | GrayscaleEffect | OutlineEffect | CustomShaderEffect | WaterEffect | FogEffect | FireEffect | RoofsCityEffect | ForestCanopyEffect | RiverWaveEffect | MoonCraterEffect | CaveInteriorEffect | MountainHillsEffect;
+type AnySpriteEffect = TintEffect | FlashEffect | GrayscaleEffect | OutlineEffect | CustomShaderEffect | WaterEffect | FogEffect | FireEffect | DropShadowEffect | RoofsCityEffect | ForestCanopyEffect | RiverWaveEffect | MoonCraterEffect | CaveInteriorEffect | MountainHillsEffect;
 /** Create a tint effect. */
 declare function tint(color: SpriteColor, amount: number): TintEffect;
 /** Create a flash effect. */
@@ -323,6 +340,14 @@ declare function fire(opts: {
     speed?: number;
     intensity?: number;
 }): FireEffect;
+/** Create a drop-shadow effect. Defaults to a soft shadow offset downward for
+ *  grounding; `color.a` is the shadow opacity. */
+declare function dropShadow(opts: {
+    color: SpriteColor;
+    offsetX?: number;
+    offsetY?: number;
+    blur?: number;
+}): DropShadowEffect;
 /** Create a rooftop city skyline effect. */
 declare function roofsCity(opts: {
     skyColor: SpriteColor;
@@ -495,6 +520,169 @@ declare const MOON_CRATER_SKSL = "\nuniform float2 resolution;\nuniform float3 m
 declare const CAVE_INTERIOR_SKSL = "\nuniform float2 resolution;\nuniform float3 caveColor;\nuniform float3 glowColor;\nuniform float scrollOffsetY;\nuniform float stalactiteCount;\n\nfloat hash(float x) { return fract(sin(x * 127.1) * 43758.5453); }\n\nfloat stalactite(float2 uv, float count) {\n  float col = floor(uv.x * count);\n  float tip = 0.1 + 0.2 * hash(col);\n  float w = 0.3 + 0.3 * hash(col + 5.0);\n  float dx = abs(fract(uv.x * count) - 0.5) / (w * 0.5);\n  float shape = step(dx, 1.0) * step(uv.y, tip * (1.0 - clamp(dx, 0.0, 1.0)));\n  return shape;\n}\n\nhalf4 main(float2 coord) {\n  float2 uv = coord / max(resolution, float2(1.0));\n  uv.y = 1.0 - uv.y;\n  uv.y = uv.y + scrollOffsetY / max(resolution.y, 1.0);\n  float stalac = stalactite(uv, stalactiteCount);\n  float glow = smoothstep(0.8, 1.0, uv.y) * (1.0 - stalac);\n  half3 col = mix(half3(caveColor.r, caveColor.g, caveColor.b),\n                  half3(glowColor.r, glowColor.g, glowColor.b),\n                  half(glow));\n  col = mix(col, half3(caveColor.r, caveColor.g, caveColor.b) * half(0.3), half(stalac));\n  return half4(col, 1.0);\n}\n";
 declare const MOUNTAIN_HILLS_SKSL = "\nuniform float2 resolution;\nuniform float3 skyColor;\nuniform float3 hillColor;\nuniform float scrollOffsetY;\nuniform float ridgeScale;\n\nfloat hash(float x) { return fract(sin(x * 127.1) * 43758.5453); }\n\nfloat heightField(float x, float scale) {\n  float h = 0.0;\n  float amp = 0.5;\n  float freq = scale;\n  for (int i = 0; i < 4; i++) {\n    float ix = floor(x * freq);\n    float fx = fract(x * freq);\n    fx = fx * fx * (3.0 - 2.0 * fx);\n    h += amp * mix(hash(ix), hash(ix + 1.0), fx);\n    freq *= 2.0;\n    amp *= 0.5;\n  }\n  return h;\n}\n\nhalf4 main(float2 coord) {\n  float2 uv = coord / max(resolution, float2(1.0));\n  float scroll = scrollOffsetY / max(resolution.y, 1.0);\n  float horizon = 0.4 + 0.3 * heightField(uv.x + scroll * 0.3, ridgeScale);\n  float mountains = step(uv.y, horizon);\n  half3 col = mix(half3(skyColor.r, skyColor.g, skyColor.b),\n                  half3(hillColor.r, hillColor.g, hillColor.b),\n                  half(mountains));\n  return half4(col, 1.0);\n}\n";
 
+/** A 4-float RGBA color buffer (r, g, b, a in [0, 1]). */
+type ColorLike = Float32Array;
+/**
+ * A mutable axis-aligned rect.
+ *
+ * The `x`, `y`, `width`, `height` fields are required so that RN-Skia's
+ * `SkHostRect` (which carries those fields) structurally satisfies this
+ * interface in contra-variant parameter positions.
+ */
+interface RectLike {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    setXYWH(x: number, y: number, w: number, h: number): void;
+}
+/**
+ * A mutable similarity transform.
+ *
+ * The `scos`, `ssin`, `tx`, `ty` fields are readable so that CK-backed
+ * canvas wrappers can flatten pools into Float32Arrays without allocation.
+ * RN-Skia's `SkRSXform` exposes all four fields.
+ */
+interface RSXformLike {
+    scos: number;
+    ssin: number;
+    tx: number;
+    ty: number;
+    set(scos: number, ssin: number, tx: number, ty: number): void;
+}
+/** A compiled SkSL runtime effect. */
+interface RuntimeEffectLike {
+    makeShader(uniforms: number[]): unknown;
+    getUniformCount(): number;
+    getUniformFloatCount(): number;
+    getUniformName(index: number): string;
+    getUniform(index: number): {
+        columns: number;
+        rows: number;
+        slot: number;
+    };
+}
+/** Color filter factory — subset used by the frame-renderer. */
+interface ColorFilterFactoryLike {
+    MakeBlend(color: Float32Array, mode: number): unknown;
+    MakeMatrix(matrix: number[]): unknown;
+}
+/** Image filter factory — optional; absent on CPU/test surfaces. */
+interface ImageFilterFactoryLike {
+    MakeDropShadow(dx: number, dy: number, sigmaX: number, sigmaY: number, color: Float32Array, input: null): unknown;
+}
+/** Runtime-effect factory — optional; absent when SkSL is unsupported. */
+interface RuntimeEffectFactoryLike {
+    Make(sksl: string): RuntimeEffectLike | null;
+}
+/** Paint — the writable subset the frame-renderer mutates. */
+interface PaintLike {
+    setAlphaf(alpha: number): void;
+    setColor?(color: Float32Array): void;
+    setColorFilter(filter: unknown): void;
+    setShader(shader: unknown): void;
+    setImageFilter(filter: unknown): void;
+}
+/** Minimal draw surface the frame-renderer calls into. */
+interface DrawSurfaceLike {
+    save(): number;
+    restore(): void;
+    translate(x: number, y: number): void;
+    scale(sx: number, sy: number): void;
+    /** rotate(radians, cx, cy) — always in radians. Web shims must convert. */
+    rotate(radians: number, cx: number, cy: number): void;
+    clear(color: Float32Array): void;
+    drawAtlas(image: unknown, srcRects: RectLike[], dstXforms: RSXformLike[], paint: PaintLike): void;
+    drawImageRect(image: unknown, src: RectLike, dst: RectLike, paint: PaintLike): void;
+    drawRect(rect: RectLike, paint: PaintLike): void;
+}
+/**
+ * Opaque picture (recorded draw commands).
+ * Typed as `object` so both `SkPicture` (RN-Skia) and CanvasKit's
+ * `SkPicture` satisfy it without structural mismatches.
+ * Callers that need concrete type methods cast to the platform type.
+ */
+type PictureLike = object;
+/** Picture recorder. */
+interface PictureRecorderLike {
+    beginRecording(bounds: RectLike): DrawSurfaceLike;
+    finishRecordingAsPicture(): PictureLike;
+}
+/**
+ * Minimal structural view of the Skia module the frame-renderer needs.
+ * Declared here so both `@flare-engine/react` and `@flare-engine/render-web`
+ * can pass their respective backends without coupling to a concrete Skia SDK.
+ *
+ * The `Surface` and `ImageFilter` slots are optional because they are absent
+ * on CPU surfaces and in test mocks.
+ */
+interface FrameRendererModule {
+    XYWHRect(x: number, y: number, w: number, h: number): RectLike;
+    RSXform(scos: number, ssin: number, tx: number, ty: number): RSXformLike;
+    Paint(): PaintLike;
+    PictureRecorder(): PictureRecorderLike;
+    ColorFilter: ColorFilterFactoryLike;
+    RuntimeEffect?: RuntimeEffectFactoryLike;
+    ImageFilter?: ImageFilterFactoryLike;
+}
+/**
+ * A single compiled postfx pass descriptor produced by the runtime.
+ */
+interface FrameRendererCompiledPass {
+    readonly id: string;
+    readonly shader: {
+        makeShaderWithChildren(uniforms: number[], children: unknown[]): unknown | null;
+        getUniformCount?(): number;
+        getUniformName?(index: number): string;
+        getUniform?(index: number): {
+            columns: number;
+            rows: number;
+            slot: number;
+        };
+    };
+    readonly uniforms: Float32Array;
+    readonly children: readonly unknown[];
+}
+/** Minimal structural view of a PostFxRuntime that the frame-renderer needs. */
+interface FrameRendererPostFxRuntime {
+    readonly supported: boolean;
+    buildPass?(chain: FrameRendererPostFxChain, width: number, height: number): readonly FrameRendererCompiledPass[];
+}
+/** Minimal structural view of an EffectChain the frame-renderer needs. */
+interface FrameRendererPostFxChain {
+    enabled(): Iterable<unknown>;
+}
+/** A resolved postfx pass descriptor with named uniforms (for React JSX). */
+interface FrameRendererPostFxDescriptor {
+    readonly id: string;
+    readonly source: unknown;
+    readonly uniforms: Record<string, number | readonly number[]>;
+    readonly children: readonly unknown[];
+}
+/**
+ * Frame renderer that bridges a `SpriteBatch` to a picture-backed draw surface.
+ *
+ * Each frame:
+ *   1. Call `beginFrame(viewportWidth, viewportHeight)`.
+ *   2. Call `drawAtlas(image, commands)` one or more times.
+ *   3. Call `endFrame()` — returns the recorded picture.
+ */
+interface FrameRenderer {
+    readonly canvas: CanvasLike;
+    beginFrame(viewportWidth: number, viewportHeight: number, time?: number, pixelDensity?: number): void;
+    drawAtlas(image: SkImageLike, commands: SpriteDrawCommand[]): void;
+    buildPostFxPasses(runtime: FrameRendererPostFxRuntime | null, chain: FrameRendererPostFxChain | null, width: number, height: number): readonly FrameRendererPostFxDescriptor[];
+    setPostFxBinding(runtime: FrameRendererPostFxRuntime | null, chain: FrameRendererPostFxChain | null): void;
+    endFrame(): PictureLike | null;
+}
+/**
+ * Create a `FrameRenderer` backed by the given structural Skia module.
+ *
+ * Both `@flare-engine/react` (passing the real RN-Skia module) and
+ * `@flare-engine/render-web` (passing a CanvasKit shim) use this factory.
+ */
+declare function createFrameRenderer(Skia: FrameRendererModule): FrameRenderer;
+
 /** A single glyph in a bitmap font. */
 interface Glyph {
     /** Character code (Unicode). */
@@ -609,4 +797,4 @@ declare function createRenderSystem(world: World, query: Query, positionDef: Com
 /** Canonical Sprite component — queried by the render system alongside `Position`. */
 declare const Sprite: ComponentDef<SpriteData>;
 
-export { type AnySpriteEffect, type BitmapFont, CAVE_INTERIOR_SKSL, Camera2D, type CanvasLike, type CaveInteriorEffect, type CompiledShader, type CustomShaderEffect, type Drawable, FIRE_SKSL, FOG_SKSL, FOREST_CANOPY_SKSL, type FireEffect, type FlashEffect, type FogEffect, type FollowOptions, type ForestCanopyEffect, type Glyph, type GrayscaleEffect, type KerningPair, MOON_CRATER_SKSL, MOUNTAIN_HILLS_SKSL, type MoonCraterEffect, type MountainHillsEffect, type OutlineEffect, type PositionData, RIVER_WAVE_SKSL, ROOFS_CITY_SKSL, type RenderStats, Renderer, type RiverWaveEffect, type RoofsCityEffect, type ShaderUniforms, Sprite, type SpriteAnchor, SpriteBatch, type SpriteColor, type SpriteData, type SpriteDrawCommand, type SpriteEffect, type TintEffect, WATER_SKSL, type WaterEffect, caveInterior, createRenderSystem, custom, drawOrderCompare, drawText, fire, flash, flashIntensity, fog, forestCanopy, getKerning, grayscale, measureText, moonCrater, mountainHills, outline, parseBMFontJSON, riverWave, roofsCity, sortByDrawOrder, tint, updateEffect, water };
+export { type AnySpriteEffect, type BitmapFont, CAVE_INTERIOR_SKSL, Camera2D, type CanvasLike, type CaveInteriorEffect, type ColorFilterFactoryLike, type ColorLike, type CompiledShader, type CustomShaderEffect, type DrawSurfaceLike, type Drawable, type DropShadowEffect, FIRE_SKSL, FOG_SKSL, FOREST_CANOPY_SKSL, type FireEffect, type FlashEffect, type FogEffect, type FollowOptions, type ForestCanopyEffect, type FrameRenderer, type FrameRendererCompiledPass, type FrameRendererModule, type FrameRendererPostFxChain, type FrameRendererPostFxDescriptor, type FrameRendererPostFxRuntime, type Glyph, type GrayscaleEffect, type ImageFilterFactoryLike, type KerningPair, MOON_CRATER_SKSL, MOUNTAIN_HILLS_SKSL, type MoonCraterEffect, type MountainHillsEffect, type OutlineEffect, type PaintLike, type PictureLike, type PictureRecorderLike, type PositionData, RIVER_WAVE_SKSL, ROOFS_CITY_SKSL, type RSXformLike, type RectLike, type RenderStats, Renderer, type RiverWaveEffect, type RoofsCityEffect, type RuntimeEffectFactoryLike, type RuntimeEffectLike, type ShaderUniforms, Sprite, type SpriteAnchor, SpriteBatch, type SpriteColor, type SpriteData, type SpriteDrawCommand, type SpriteEffect, type TintEffect, WATER_SKSL, type WaterEffect, caveInterior, createFrameRenderer, createRenderSystem, custom, drawOrderCompare, drawText, dropShadow, fire, flash, flashIntensity, fog, forestCanopy, getKerning, grayscale, measureText, moonCrater, mountainHills, outline, parseBMFontJSON, riverWave, roofsCity, sortByDrawOrder, tint, updateEffect, water };