Scene backgrounds

The root background (and each surface’s background) uses the same shape as CanvasConfig minus the required width / height on the scene object — those come from SceneRenderInput.width/height or from placement.width/height for surfaces.

Painting is done by CanvasCreator.composeCanvasForScene → paintConfiguredCanvasSurface (gradients, bgLayers, patternBg, noiseBg, clip, zoom, shadow, stroke, videoBg if extraction is wired, etc.). Deep behaviour: Canvas backgrounds, bg-layers, transparent base.

#Variant: flat color

1const scene = {2  width: 800,3  height: 450,4  background: { colorBg: "#0f172a" },5  layers: [/* … */],6};

##Transparent “letterbox” feel

1background: { colorBg: "transparent" },

Combine with transparentBase: true and bgLayers if you need a stacked transparent stack (see transparent base).

#Variant: linear gradient (sketch)

1background: {2  gradientBg: {3    type: "linear",4    x0: 0,5    y0: 0,6    x1: 800,7    y1: 450,8    colors: [9      { stop: 0, color: "#1e293b" },10      { stop: 1, color: "#0f172a" },11    ],12  },13},

(Match your gradient type from Gradients / canvas docs.)

#Variant: full-screen image

1background: {2  customBg: {3    source: "./assets/hero.jpg",4    fit: "cover",5    align: "center",6  },7},

##Inherit image dimensions (root scene)

If customBg.inherit: true, CanvasCreator can set width/height from the image — you may omit width/height on SceneRenderInput only when that resolution path runs successfully; otherwise set explicit width/height.

#Variant: bgLayers stack (tint over image)

1background: {2  customBg: { source: "./bg.png", fit: "cover", align: "center" },3  bgLayers: [4    { type: "color", value: "#000000", opacity: 0.35, blendMode: "source-over" },5    { type: "noise", intensity: 0.04 },6  ],7},

##Only layers, no primary fill

1background: {2  transparentBase: true,3  bgLayers: [4    { type: "gradient", value: { /* … */ }, opacity: 1 },5  ],6},

#Variant: pattern + noise

1background: {2  colorBg: "#ffffff",3  patternBg: { /* PatternOptions — see pattern guide */ },4  noiseBg: { intensity: 0.03 },5},

#Variant: border, shadow, zoom (card-style root)

1background: {2  colorBg: "#fff",3  x: 24,4  y: 24,5  width: 752,6  height: 402,7  borderRadius: 16,8  shadow: {9    color: "rgba(0,0,0,0.15)",10    offsetX: 0,11    offsetY: 8,12    blur: 24,13  },14  stroke: { color: "#e2e8f0", width: 1 },15},

Note: For root scene, width/height on SceneRenderInput are still the full bitmap size; x,y,width,height on background define the clipped rounded rect inside that bitmap (same as createCanvas).

#videoBg caveat

CanvasConfig.videoBg requires CanvasCreator.setExtractVideoFrame to be set (typically from video stack wiring). If unset, videoBg may not size or paint. Prefer customBg with a still frame you extracted yourself if you need reliability without that hook.