@salsita-ai/sdk 0.0.0-stage → 0.49.0-develop.cbee856178

package/dist/docs/phoenix/blender-rendering.mdx

@@ -0,0 +1,450 @@
+# Blender Rendering
+
+- [Generate an image from the submitted configuration](#generate-an-image-from-the-submitted-configuration)
+- [Export states and scene scale](#export-states-and-scene-scale)
+- [What Phoenix projects from the domain](#what-phoenix-projects-from-the-domain)
+- [Rendered entities](#rendered-entities)
+- [Material overrides](#material-overrides)
+  - [Scalar and color values](#scalar-and-color-values)
+  - [Texture maps](#texture-maps)
+  - [Removing authored textures with `null`](#removing-authored-textures-with-null)
+  - [Transparency](#transparency)
+- [Lights](#lights)
+- [Camera projection](#camera-projection)
+- [Template camera and extended camera fields](#template-camera-and-extended-camera-fields)
+- [Render settings](#render-settings)
+- [Several images in one task](#several-images-in-one-task)
+- [Lower-level projections](#lower-level-projections)
+- [Assets, caching, and failures](#assets-caching-and-failures)
+- [Known gaps](#known-gaps)
+- [Custom render scripts](#custom-render-scripts)
+
+Use a **`GenerateImages`** finalization task when an order, quote, PDF, or email needs a server-rendered image of the submitted configuration. Phoenix can project a complete export-aware image configuration with a generated camera, or just the scene content when you want to supply a custom camera or use the camera from your `.blend` template. The rendering worker opens that template in headless Blender, imports the glTF files you name, applies the payload, and uploads the result as the image resource named in the task.
+
+This page describes what the default render script supports and how it behaves. For where the task sits in the finalization flow, see [Webhooks → GenerateImages Task](?path=/docs/phoenix-webhooks--docs#generateimages-task) and [Finalization](?path=/docs/phoenix-finalization--docs).
+
+## Generate an image from the submitted configuration
+
+Start with **`ctx.blenderProjections.getBlenderImageConfig`** instead of manually assembling objects, lights, and a camera. It applies the requested export state and its transformers once, validates the resulting state, and returns the output dimensions, rendered entities, lights, and an aspect-aware camera projected from that same state.
+
+The example assumes an `Image` resource named `heroPng`, `template.blend` and `scene.gltf` uploaded as [private static assets](?path=/docs/phoenix-webhooks--docs#static-assets), and a perspective camera active for the `Default` export state. See [Resources](?path=/docs/phoenix-webhooks--docs#resources) for defining the generated image resource.
+
+```typescript
+export const heroImageTask = phx.webhooks.taskFactory.createGenerateImagesTask((resources, data, ctx) => {
+  const imageSize = { width: 1920, height: 1080 }
+  const imageConfig = ctx.blenderProjections.getBlenderImageConfig(
+    data.state,
+    'Default',
+    data.state.rootEntityId,
+    imageSize
+  )
+
+  return {
+    type: 'GenerateImages',
+    deploymentId: data.deploymentId,
+    blenderSetupTemplate: 'template.blend',
+    templateFiles: ['scene.gltf'],
+    renderSettings: {
+      samples: 256,
+      viewTransform: 'Filmic',
+      filmTransparent: true,
+    },
+    images: [
+      {
+        name: resources.heroPng,
+        fileFormat: 'PNG',
+        ...imageConfig,
+        renderSettings: {
+          exposure: 0.5,
+        },
+        camera: {
+          ...imageConfig.camera,
+          dof: { enabled: true, apertureFstop: 2.8 },
+          sensorWidth: 36,
+        },
+      },
+    ],
+  }
+})
+```
+
+For a custom camera, use **`getBlenderSceneConfig`** to prepare the exported entities and lights without calculating a camera that the task will discard:
+
+```typescript
+import type { BlenderCamera } from '@salsita-ai/sdk/domain'
+
+const imageSize = { width: 1920, height: 1080 }
+const sceneConfig = ctx.blenderProjections.getBlenderSceneConfig(data.state, 'RoomImage', data.state.rootEntityId)
+const customCamera: BlenderCamera = {
+  position: [3, -3, 2],
+  target: [0, 0, 0],
+}
+
+const image = {
+  ...imageSize,
+  ...sceneConfig,
+  camera: customCamera,
+}
+```
+
+Omit `camera` entirely to use the active camera from the `.blend` template.
+
+The authoritative payload and validation types live in **`@salsita-ai/sdk/contracts/webhook`**. The domain entry point also exports **`BlenderCamera`**, **`BlenderRenderedEntity`**, **`BlenderImageConfig`**, **`BlenderSceneConfig`**, **`BlenderRenderSettings`**, **`BlenderCameraDof`**, and **`BlenderMaterialOverride`** for custom task builders.
+
+| Property                  | Purpose                                                                                                                                                               |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `blenderSetupTemplate`    | The `.blend` file opened for every image. It provides the world, render engine, compositor, and optionally the camera.                                                |
+| `templateFiles`           | glTF or GLB files imported into the template. Their objects are the templates that `default` entities clone.                                                          |
+| `blenderPythonScriptName` | Optional custom script from the private deployment assets; omit it to use the default script described on this page.                                                  |
+| `renderSettings`          | Task-level defaults merged under each image's own `renderSettings`; see [Render settings](#render-settings).                                                          |
+| `images[].name`           | The image resource that receives the render. It is also the file name written by the worker, so it must be a single path segment.                                     |
+| `images[].fileFormat`     | `PNG` or `JPEG`.                                                                                                                                                      |
+| `images[].width/height`   | Output resolution in pixels, rendered at 100 %.                                                                                                                       |
+| `images[].camera`         | Optional look-at camera; omit it to render with the template's camera. See [Template camera and extended camera fields](#template-camera-and-extended-camera-fields). |
+| `images[].lights`         | Lights created for this image only. See [Lights](#lights).                                                                                                            |
+
+All coordinates in the payload are Blender coordinates: meters, Z up, quaternions in `(w, x, y, z)` order.
+
+## Export states and scene scale
+
+The projection reads the domain, not the viewer, so everything the render needs has to be declared for the export state it renders. In practice:
+
+- **Give each render its own export state.** Export states carry no view state, so a component filtered by `viewStates` is inactive while rendering. Declare an export state per view (`Blender`, `BlenderDetail`, …) and add it to the `$filter.exportStates` of every camera, object, light, and material override that view needs. A viewer room that lives in a `viewStates` filter needs an export-state twin.
+- **Environments come from the domain or the template.** Rooms, stands, and lights rendered by React code never reach Blender. Declare them as remote objects and light components active in the render export states, or bake them into the `.blend` template.
+- **Check the scene scale before tuning the camera.** Blender units are metres. Each object's `dimensionUnit` scales its geometry and positions convert from the application's distance unit, so a product authored in metres but declared in inches renders at 1/39 of its size. If the whole scene is a few centimetres across, lower `camera.clipStart` (for example `0.001`) and expect depth-of-field f-stops in the tens to hundreds rather than photographic values, because the aperture is compared with the tiny scene.
+- **Prefer AgX for product shots.** `viewTransform: 'AgX'` with an `AgX - Medium High Contrast` look keeps saturated finishes from clipping; `Filmic` is the Blender 3.x default and still works.
+
+The precision demo in `packages/demos/demo-precision` shows all four: an export state per rendered view, a YAML-declared exhibition and studio environment, a millimetre clip start, and AgX with compositor glare.
+
+## What Phoenix projects from the domain
+
+| Scene concern | Blender behavior                                                                                                                                                                                                                                                            |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Objects       | Remote scene objects are emitted with their Blender object name, world position, quaternion rotation, scale, morph-target influences, and material overrides. Objects use the application's distance unit when they do not declare their own unit.                          |
+| Hierarchy     | Entity transforms and nested `sceneEntityObjectGroup` transforms are composed before Three.js Y-up coordinates are converted to Blender Z-up coordinates. Hidden entity subtrees, hidden object groups, and objects with `visible: false` or `rendered: false` are omitted. |
+| Materials     | Entity-level overrides flow from parent to child; the nearest entity or object override wins. Material-property transition end values are applied to the exported state. Supported PBR scalar, color, and texture-map values are projected.                                 |
+| Lights        | Point, spot, directional, and rectangular area lights include their world transform and Blender-specific settings. Targeted lights receive explicit rotations so their direction matches the configurator.                                                                  |
+| Camera        | The highest-priority active perspective camera supplies the pose and field of view. Static, fit-root, and fit-entity perspective cameras are supported.                                                                                                                     |
+
+`getBlenderImageConfig` and `getBlenderSceneConfig` do not project domain custom entities (objects and lights in that subtree are skipped) or non-remote scene objects. Text decals, object decals, object transformers, and animation clips are not applied and Phoenix logs which object carries them; material override transformers are not applied and are logged per entity. Ambient lights have no direct Blender equivalent and are omitted; use HDRI lighting or point/area lights instead.
+
+## Rendered entities
+
+`default` entities clone an object from the imported template files. Projected entities are identified as `<entityId>_<objectInstanceName>`, and the default script names the clone after the template object plus that id. `objectName` must match the imported object's name. The clone receives `position`, the optional quaternion `rotation`, and an optional `scale` that is multiplied with the template object's authored scale. The projected rotation is composed before the template object's authored rotation, so a template authored at an angle keeps that angle under the projected one. When the template object is an empty parent, a new parent empty receives the position, the composed rotation, and the scale, and every child is cloned under it with its local transform intact.
+
+`morphTargetInfluences` maps shape-key names to influence values. The worker applies them directly to the mesh vertices before rendering, so influences are not limited to Blender's shape-key slider range. Nonzero weights authored in the template stay active unless the same shape key is overridden; an explicit `0` disables an authored default. When several morphs are active, their authored deltas, including deltas from relative shape keys, are combined in the final geometry. Unknown shape keys are logged and skipped. An object without shape keys forwards the influences to its children.
+
+`custom` entities are meant for a custom script, but the default script handles two shapes: `shape: 'plane'` adds a unit plane at `position` with the optional `rotation` and `scale`; any other custom entity must carry `vertices` and `faces` and becomes a new mesh with automatically projected UVs. Material overrides on custom entities create new materials instead of overriding template ones, and their textures use box projection scaled by the object's height rather than UVs.
+
+Generated Blender names longer than Blender's 63-character limit receive a deterministic hash suffix so long names do not collide.
+
+## Material overrides
+
+Domain projection carries base color, roughness, metalness, emissive color/intensity, opacity, clearcoat, sheen, specular, IOR, transmission, anisotropy, displacement, their supported texture maps, map intensity/scale values, and texture tiling. Parent material overrides are applied before child and object-specific overrides, so the nearest matching override wins. Texture offsets and rotation, iridescence, environment-map intensity, tone mapping, thickness and attenuation, and reflectivity are not projected to Blender.
+
+`materialOverrides` is a record keyed by any name you choose. Each override names the template material it replaces through `baseMaterialName` (the key is used when it is omitted) and carries the PBR values to apply. The worker looks the material up on the cloned object by exact name first, then by the `name.001`-style suffix Blender adds to duplicates, then on the object's children. A missing material or a material without a Principled BSDF node is logged and left unchanged. The template material itself is never modified; every override works on a copy assigned to the clone.
+
+### Scalar and color values
+
+| Property                                   | Blender input                     |
+| ------------------------------------------ | --------------------------------- |
+| `color`                                    | Base Color                        |
+| `emissive`, `emissiveIntensity`            | Emission Color, Emission Strength |
+| `roughness`, `metalness`                   | Roughness, Metallic               |
+| `opacity`                                  | Alpha                             |
+| `clearcoat`, `clearcoatRoughness`          | Coat Weight, Coat Roughness       |
+| `sheen`, `sheenRoughness`, `sheenColor`    | Sheen Weight, Roughness, Tint     |
+| `specularIntensity`, `specularColor`       | Specular IOR Level, Specular Tint |
+| `ior`, `transmission`                      | IOR, Transmission Weight          |
+| `anisotropyStrength`, `anisotropyRotation` | Anisotropic, Anisotropic Rotation |
+
+Colors are six-digit hex strings, or one of the simple color names `white`, `black`, `red`, `green`, `blue`, `yellow`, `cyan`, and `magenta`, and are converted to linear RGB. Any other value, including RAL codes, is omitted from the payload with a logged warning, so the template's authored color stays in place. Setting any of these values disconnects whatever the template had wired into that input, so a scalar `roughness` replaces an authored roughness texture as well as the authored factor. `normalScale`, `bumpScale`, `aoMapIntensity`, `clearcoatNormalScale`, `displacementScale`, `repeatX`, and `repeatY` only have an effect together with their texture map. Blender 3.x input names are supported as fallbacks for the 4.x names listed above.
+
+### Texture maps
+
+A texture map is a path to an image in the private deployment assets. The worker downloads it into the deployment cache before Blender starts. Maps share one UV mapping node whose scale is `repeatX` × `repeatY` (both default to `1`). An image that fails to load is logged and skipped; the rest of the override still applies.
+
+| Property                   | Blender wiring                                                                                                 |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `textureUrl`               | Base Color. When `color` is also set, the texture is multiplied by the color as a tint.                        |
+| `normalMapUrl`             | Normal Map node with `normalScale` strength into Normal.                                                       |
+| `bumpMapUrl`               | Bump node with `bumpScale` strength into Normal, chained after the normal map when both are present.           |
+| `aoMapUrl`                 | Multiplied into Base Color with `aoMapIntensity` as the mix factor.                                            |
+| `roughnessMapUrl`          | Roughness                                                                                                      |
+| `metalnessMapUrl`          | Metallic                                                                                                       |
+| `alphaMapUrl`              | Alpha; see [Transparency](#transparency).                                                                      |
+| `anisotropyMapUrl`         | Anisotropic                                                                                                    |
+| `clearcoatMapUrl`          | Coat Weight                                                                                                    |
+| `clearcoatRoughnessMapUrl` | Coat Roughness                                                                                                 |
+| `clearcoatNormalMapUrl`    | Normal Map node with `clearcoatNormalScale` strength into Coat Normal.                                         |
+| `sheenColorMapUrl`         | Sheen Tint                                                                                                     |
+| `sheenRoughnessMapUrl`     | Sheen Roughness                                                                                                |
+| `specularIntensityMapUrl`  | Specular IOR Level                                                                                             |
+| `specularColorMapUrl`      | Specular Tint                                                                                                  |
+| `transmissionMapUrl`       | Transmission Weight                                                                                            |
+| `displacementMapUrl`       | Displacement node with `displacementScale` into the Material Output, so the template must enable displacement. |
+
+Non-color maps are loaded in the `Non-Color` color space; `textureUrl`, `sheenColorMapUrl`, and `specularColorMapUrl` keep the image's color space. A map whose input does not exist in the worker's Blender version is logged and skipped.
+
+### Removing authored textures with `null`
+
+Every texture-map property distinguishes three values:
+
+- a **path** applies that map, replacing whatever the template had on that input;
+- **`null`** removes the texture the template author connected to that input and leaves the input at its neutral value (`1` for scalars, white for colors) or at the factor the glTF importer multiplied the texture with;
+- **omission** leaves the authored map untouched.
+
+Removal targets the node graphs produced by Blender's glTF importer, identified by the labels it puts on image texture nodes. A texture is removed when it feeds the input directly, through a Separate Color node, or through a chain of Math or Mix nodes in which exactly one input leads back to the texture and the other carries the authored factor:
+
+| Property                                   | Importer label the worker looks for                        |
+| ------------------------------------------ | ---------------------------------------------------------- |
+| `textureUrl`, `alphaMapUrl`                | `BASE COLOR` (also behind an AO mix node for `textureUrl`) |
+| `roughnessMapUrl`, `metalnessMapUrl`       | `METALLIC ROUGHNESS`                                       |
+| `anisotropyMapUrl`                         | `ANISOTROPY` (the importer's vector-math pattern is reset) |
+| `clearcoatMapUrl`                          | `CLEARCOAT`                                                |
+| `clearcoatRoughnessMapUrl`                 | `CLEARCOAT ROUGHNESS`                                      |
+| `sheenColorMapUrl`, `sheenRoughnessMapUrl` | `SHEEN COLOR`, `SHEEN ROUGHNESS`                           |
+| `specularIntensityMapUrl`                  | `SPECULAR`                                                 |
+| `specularColorMapUrl`                      | `SPECULAR COLOR`                                           |
+| `transmissionMapUrl`                       | `TRANSMISSION`                                             |
+
+`normalMapUrl`, `bumpMapUrl`, `clearcoatNormalMapUrl`, `aoMapUrl`, and `displacementMapUrl` do not depend on labels: `null` disconnects the Normal, Coat Normal, or Displacement input, bypasses a Bump node while keeping the normal map behind it, or bypasses the importer's AO mix and Occlusion inputs while restoring the original base color.
+
+When the authored graph does not match a supported pattern the texture stays connected and the worker logs `Could not remove texture map "<property>"`. Hand-built templates need the importer's labels on their image texture nodes for removal to work.
+
+### Transparency
+
+`transparent` controls the material's surface mode and is applied after every other value:
+
+- **omitted** keeps the template material's mode. `opacity` still sets Alpha; Cycles honors it on any material, EEVEE honors it in Blender 4.2 and newer, and before 4.2 EEVEE ignores it on materials whose blend mode is opaque.
+- **`true`** switches the material to Blender's `BLENDED` surface method (`BLEND` before Blender 4.2) so `opacity` and `alphaMapUrl` render as see-through.
+- **`false`** disconnects anything wired into Alpha, sets Alpha to `1`, and switches to `DITHERED` (`OPAQUE` before Blender 4.2). It wins over `opacity` and `alphaMapUrl` in the same override.
+
+The same three values are accepted by the viewer's remote material override, so a domain value can be forwarded unchanged; see [Material Override](?path=/docs/3d-scene-materials-override--docs).
+
+## Lights
+
+All four domain light types project position, color, intensity, and their type-specific settings:
+
+| Domain light                  | Blender type | Additional projected settings                                                   |
+| ----------------------------- | ------------ | ------------------------------------------------------------------------------- |
+| `sceneEntityPointLight`       | `POINT`      | shadows, radius                                                                 |
+| `sceneEntitySpotLight`        | `SPOT`       | target/rotation, angle, penumbra, shadows, radius, cone visibility, `useSquare` |
+| `sceneEntityDirectionalLight` | `SUN`        | target/rotation, shadows, Blender angle                                         |
+| `sceneEntityRectAreaLight`    | `AREA`       | target/rotation, width, height, shape, spread, and `roll` around the aimed beam |
+
+Every supported light can set Blender-only `specularFactor`, `diffuseFactor`, and `volumeFactor`. Light colors use the same hex/simple-name normalization as material colors. Invalid colors are omitted rather than failing the render. Top-level `intensity` controls the Three.js preview and is also the Blender fallback; set `blender.intensity` only when the Blender export needs a different value.
+
+```yaml
+components:
+  Scene:
+    sceneEntitySpotLight:
+      ledLight:
+        intensity: 5000
+        blender:
+          intensity: 1000
+```
+
+Lights are created per image with `id` as the Blender object name. `position` is required; `color` is a six-digit hex string and `intensity` is Blender energy. `castShadow`, `specularFactor`, `diffuseFactor`, and `volumeFactor` apply to every type. Type-specific settings:
+
+| `type`  | Settings                                                                                                                                                  |
+| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `POINT` | `radius` (shadow softness)                                                                                                                                |
+| `SPOT`  | `angle` (half cone angle in radians, doubled to Blender's full cone), `penumbra` (edge blend), `radius`, `showCone`, `useSquare`                          |
+| `SUN`   | `blenderAngle` (angular diameter in radians)                                                                                                              |
+| `AREA`  | `shape` (`SQUARE`, `RECTANGLE` (default), `DISK`, `ELLIPSE`), `width` and `height` in millimeters (height applies to `RECTANGLE` and `ELLIPSE`), `spread` |
+
+`SPOT`, `SUN`, and `AREA` lights aim at `target` when it is set: the worker rotates the light to face it, unless `rotation` is also given, in which case that quaternion is used verbatim and `target` only enables it. `POINT` lights ignore both.
+
+## Camera projection
+
+Blender cameras follow the same orbit rules as interactive configurator cameras:
+
+- `relative: true` transforms a static target through the owning entity's world matrix and adds its world Y rotation to the azimuth and azimuth limits.
+- Azimuth and polar angles are clamped to their configured bounds, including ranges that wrap across 0/2π.
+- Camera distances and bounds use the application's distance data unit and are converted consistently before the Blender payload is converted to meters.
+- Explicit and automatically fitted distances are clamped to `minDistance` and `maxDistance`.
+- A static camera without `distance` starts from a fallback of `0`, then clamps to `minDistance` (`Number.EPSILON` when no minimum is configured). Set an explicit `distance` for a usable static render.
+
+Fit cameras use sphere fitting by default and require a `boundingSphere` on the fitted entity. Set `fitToBox: true` and provide a `boundingBox` for box fitting. Both strategies use the requested image aspect ratio. The worker cannot fall back to fitting a loaded Three.js mesh.
+
+Orthographic camera components are not supported for Blender rendering. If the highest-priority active camera is orthographic, projection fails with an error instead of silently treating it as perspective.
+
+For authoring camera components and bounds, see [Static Camera](?path=/docs/3d-scene-cameras-static--docs) and [Fit Root Camera](?path=/docs/3d-scene-cameras-fit-root--docs).
+
+### Reusing the camera-orbit projections
+
+Custom projections can import the same orbit functions used by the configurator and Blender exporter. This example assumes `cameraState` is a camera component state, `entityWorldMatrix` is its owning entity's current world matrix, and `dimensionUnit` is the application's current distance data unit:
+
+```typescript
+import { Matrix4 } from 'three'
+
+import { cameraOrbitToCartesian, resolveCameraDistance, resolveCameraOrbit } from '@salsita-ai/sdk/domain'
+
+const orbit = resolveCameraOrbit({
+  state: cameraState,
+  dimensionUnit,
+  worldMatrix: cameraState.relative ? entityWorldMatrix : new Matrix4(),
+})
+const distance = resolveCameraDistance(orbit.distance, orbit, 1000)
+const cameraOffset = cameraOrbitToCartesian(orbit.azimuthAngle, orbit.polarAngle, distance)
+```
+
+`resolveCameraOrbit` returns world-space angles and distances in Phoenix's default distance unit (millimeters). The `worldMatrix` is used only for a relative camera. The fallback passed to `resolveCameraDistance` must already use the default distance unit.
+
+## Template camera and extended camera fields
+
+Omit `camera` to render with the template's camera. The worker uses the scene's active camera, then any camera object in the scene, then any camera data block in the file, and fails with a clear error when the template has none.
+
+With `camera` set, the worker adds a camera at `position` that tracks `target` through a look-at constraint. Optional fields:
+
+| Property      | Purpose                                                                                                                          |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `fov`         | Vertical field of view in degrees, default `50`.                                                                                 |
+| `sensorWidth` | Sensor width in millimeters.                                                                                                     |
+| `clipStart`   | Near clipping distance in meters.                                                                                                |
+| `clipEnd`     | Far clipping distance in meters.                                                                                                 |
+| `dof`         | `enabled` turns depth of field on; `apertureFstop` sets the aperture; `focusDistance` defaults to the camera-to-target distance. |
+
+## Render settings
+
+`renderSettings` may appear on the task and on each image; the worker merges image settings over task settings key by key, so an image only needs the values it changes. Every setting is optional and only the keys you send are touched. Values must be valid for the Blender version installed on the worker.
+
+### Color management and film
+
+| Property          | Purpose                                                                          |
+| ----------------- | -------------------------------------------------------------------------------- |
+| `exposure`        | View transform exposure.                                                         |
+| `viewTransform`   | `AgX`, `Filmic`, `Standard`, or `Raw`.                                           |
+| `look`            | Look preset for the view transform, as named in Blender.                         |
+| `gamma`           | Display gamma.                                                                   |
+| `filmTransparent` | Render with a transparent background, for example for PNGs composited elsewhere. |
+
+### Sampling and light paths
+
+| Property         | Purpose                                                                      |
+| ---------------- | ---------------------------------------------------------------------------- |
+| `samples`        | Cycles samples, or EEVEE render samples, depending on the template's engine. |
+| `useDenoising`   | Cycles only: enable denoising.                                               |
+| `denoiser`       | Cycles only: `OPENIMAGEDENOISE` or `OPTIX`.                                  |
+| `maxBounces`     | Cycles only: maximum light-path bounces.                                     |
+| `diffuseBounces` | Cycles only: diffuse bounces.                                                |
+| `glossyBounces`  | Cycles only: glossy bounces.                                                 |
+
+Cycles-only keys are ignored on EEVEE templates.
+
+### HDRI and world
+
+| Property       | Purpose                                                                                          |
+| -------------- | ------------------------------------------------------------------------------------------------ |
+| `hdriFile`     | HDRI image from the private deployment assets, loaded into the world's Environment Texture node. |
+| `hdriStrength` | Strength of the world Background node.                                                           |
+| `hdriRotation` | Rotation around Z in radians, applied to the world's Mapping node.                               |
+
+The worker reuses the template's Environment Texture node and creates one connected to the Background node when the world has none. `hdriStrength` and `hdriRotation` need an existing Background or Mapping node respectively; otherwise they are skipped with a warning, so author those nodes in the template.
+
+### Compositor effects
+
+These settings add nodes between the template's Render Layers and Composite nodes; a template without both nodes skips them with a warning.
+
+| Property              | Purpose                                          |
+| --------------------- | ------------------------------------------------ |
+| `glareEnabled`        | Add a fog-glow glare pass.                       |
+| `glareThreshold`      | Glare threshold.                                 |
+| `glareIntensity`      | Glare mix.                                       |
+| `lensDistortion`      | Lens distortion amount.                          |
+| `chromaticAberration` | Lens dispersion.                                 |
+| `vignette`            | Vignette strength; values above `0` enable it.   |
+| `filmGrain`           | Film-grain strength; values above `0` enable it. |
+
+### World volumetrics
+
+| Property                  | Purpose                                                                                |
+| ------------------------- | -------------------------------------------------------------------------------------- |
+| `volumeScatterDensity`    | Density of a Volume Scatter node on the world output; the node is created when absent. |
+| `volumeScatterAnisotropy` | Scatter anisotropy; only applied together with `volumeScatterDensity`.                 |
+
+## Several images in one task
+
+All images of a task render in one Blender process against the same template, one after another. Before each image the worker deletes everything it created for the previous one (cloned objects, their override materials, lights, and the look-at camera), restores the template's color management, film, sampling, compositor, and world settings, and removes every Volume Scatter node from the world. That reset also runs before the first image, so author volumetrics through `volumeScatterDensity` rather than in the template. Imported template objects stay hidden from render and are only ever cloned. Nothing from one image leaks into the next, and each image's `renderSettings` starts from the task-level defaults again.
+
+## Lower-level projections
+
+`getBlenderImageConfig` composes public projections you can call yourself when a task needs something the combined result does not give you, such as a hand-placed camera, a scene rendered from the current state without an export update, or a subset of the objects:
+
+| Method                                              | Result                                                                                                                                                  |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getSceneEntityTree(state)`                         | The entity tree with each entity's world matrix, scene objects, overrides, transformers, clips, and lights. This is the input of the other projections. |
+| `getBlenderObjects(state)`                          | Flat rendered objects: `id`, `objectName`, Blender `position`, optional `rotation` and `scale`, `morphTargetInfluences`, and `materialOverrides`.       |
+| `getBlenderLights(state)`                           | Blender lights with world positions, targets, and rotations.                                                                                            |
+| `getBlenderCamera(state, imageSize)`                | The highest-priority active perspective camera as a Blender look-at camera fitted to `imageSize`.                                                       |
+| `getBlenderSceneConfig(state, exportState, entity)` | `renderedEntities` and `lights` from a prepared export state, without a camera. Use it with the template camera or an explicit one.                     |
+
+The first four take the state as it is, so components filtered by `exportStates` are inactive unless the state already carries that export state; `getBlenderSceneConfig` and `getBlenderImageConfig` prepare and validate the export state for you, and `getBlenderSceneConfig` is the entry point when you only want to replace the camera. The result types (`BlenderSceneObject`, `SceneEntityNode`, `SceneEntityObject`) are exported from the domain entry point. The example below renders the current state with a fixed camera:
+
+```typescript
+export const simpleImageTask = phx.webhooks.taskFactory.createGenerateImagesTask((resources, data, ctx) => {
+  const objects = ctx.blenderProjections.getBlenderObjects(data.state)
+
+  return {
+    type: 'GenerateImages',
+    deploymentId: data.deploymentId,
+    blenderSetupTemplate: 'template.blend',
+    templateFiles: ['scene.gltf'],
+    images: [
+      {
+        name: resources.simpleImage,
+        fileFormat: 'PNG',
+        width: 1920,
+        height: 1080,
+        renderedEntities: objects.map(o => ({
+          id: o.id,
+          type: 'default',
+          objectName: o.objectName,
+          position: o.position,
+          rotation: o.rotation,
+          scale: o.scale,
+          materialOverrides: o.materialOverrides,
+          morphTargetInfluences: o.morphTargetInfluences,
+        })),
+        camera: {
+          position: [0, -5, 9],
+          target: [0, 0, 0],
+        },
+      },
+    ],
+  }
+})
+```
+
+## Assets, caching, and failures
+
+- `blenderSetupTemplate`, `templateFiles`, `blenderPythonScriptName`, texture maps, and HDRIs are paths relative to the private deployment assets (see [Static assets](?path=/docs/phoenix-webhooks--docs#static-assets)). A leading slash is removed and backslashes become `/`; URL schemes, network paths, empty or directory paths, control characters, and any `..` segment are rejected.
+- `images[].name` becomes the rendered file name, so it must be a single non-empty path segment without slashes, control characters, `.`, or `..`.
+- Assets are cached per deployment and reused by later jobs. Texture and HDRI references are downloaded and rewritten to their cache paths before Blender starts, so the script only ever sees local files.
+- Blender runs with factory settings, so add-ons and user preferences on the worker do not affect the render. The render engine is the worker's configured engine.
+- A non-zero Blender exit fails the finalization task. Blender's stderr is included in the reported error, and every stdout and stderr line is forwarded to the worker log, including the material and texture warnings described above.
+- Unsupported values inside a material override (for example a map on an input the worker's Blender version lacks) are logged and skipped rather than failing the render; invalid render-setting enum values fail the render.
+
+## Known gaps
+
+The projection and the default render script cover the domain scene, not everything the configurator draws. What is not rendered, and how it fails:
+
+| Gap                              | Behavior                                                                                                                                                                                                                                                                                                                                                                                                              |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Custom scene entities            | An entity with a `customSceneEntity` component is skipped together with its whole subtree, objects and lights alike, and logged once. Declare the parts it draws as remote objects, active only in the export state used for rendering, when they must appear in Blender.                                                                                                                                             |
+| Code-rendered environments       | Rooms, stands, lights, and effects rendered by a `canvasCustomEnvironment` or other React code never reach the projection. Only domain components are exported; the `.blend` template or domain light and object components must provide the environment.                                                                                                                                                             |
+| Non-remote objects and overrides | `sceneEntityObject` and `sceneEntityBoxObject` objects and local material overrides (`sceneEntityMaterialOverride`, `sceneEntityObjectMaterialOverride`, `sceneEntityLocalMaterialOverride`, `sceneEntityObjectLocalMaterialOverride`, transmissive overrides) are skipped with a `not a remote object` or `not a remote material override` warning; only remote objects and remote material overrides are projected. |
+| Decals and ambient light         | Text decals and object decals are logged and ignored. Ambient lights are omitted; use HDRI lighting or point and area lights.                                                                                                                                                                                                                                                                                         |
+| Animation and transformers       | Material-property transitions render at their end color. Animation clips and object transformers are not applied and are logged per object; material override transformers are not applied and are logged per entity. Put the final values on the properties and overrides active in the export state.                                                                                                                |
+| Unprojected material properties  | Texture offsets and rotation, iridescence, environment-map intensity, light maps, tone mapping, thickness and attenuation, reflectivity, blending mode, and wireframe are not projected. Colors that are neither hex nor a supported simple name are omitted with a warning.                                                                                                                                          |
+| Orthographic cameras             | Projection fails when the active camera is orthographic. Fit cameras also need a `boundingSphere` or `boundingBox` because meshes are not loaded server-side.                                                                                                                                                                                                                                                         |
+| Nested template empties          | The default script clones an empty template object with its direct children only. An empty nested inside another empty raises an error, so flatten such groups in the glTF or export the leaf meshes as separate objects.                                                                                                                                                                                             |
+| Scene scale                      | Blender units are metres. Each object's `dimensionUnit` converts its authored geometry, and positions convert from the default distance unit, so a product authored in metres but declared as inches renders at 1/39 of its size. See [Export states and scene scale](#export-states-and-scene-scale) for the camera consequences.                                                                                    |
+| Blender versions                 | The rendering worker image runs Blender 4.1. The script also runs on 4.2 and 5.x, where transparency modes and the compositor tree location differ, but a `.blend` template saved by a newer major release than the worker's fails with `not a blend file` or `saved by a newer version`, so author templates with the worker's release.                                                                              |
+| Resource coverage                | Every `Image` resource declared in `spec/application.yaml` or `spec/finalization.yaml` must be produced by a task in every finalization, so a `GenerateImages` task cannot be skipped for some deliveries without also dropping its resources.                                                                                                                                                                        |
+| Morph target ranges              | A `morphTargetInfluences` entry whose `scaleZero` equals `scaleOne` has no defined weight; it is exported as `0` with a warning instead of sending `NaN` to Blender, matching the unmorphed mesh the viewer shows.                                                                                                                                                                                                    |
+
+## Custom render scripts
+
+Set `blenderPythonScriptName` to a Python file in the private deployment assets to replace the default script. The worker writes the job data (cached template paths and the image jobs, with texture and HDRI paths already rewritten to the cache) to `./tmp/data.json` in its working directory, opens `blenderSetupTemplate`, and runs the script in the background; the script must exit non-zero on failure so the task fails instead of uploading a missing image. Custom entities (`type: 'custom'`) are the intended way to pass extra data to such a script; the worker still downloads any texture maps found in their `materialOverrides` when those parse as material overrides.

package/dist/docs/phoenix/clerk-sign-in.mdx

@@ -0,0 +1,82 @@
+# Clerk Sign-In
+
+Phoenix projects that use Clerk can replace the redirect-only OAuth entry point with an inline sign-in page for the Configurator, Admin, or both. The integration is opt-in through `@salsita-ai/sdk/extras/clerk`; projects without `useClerk` do not install or bundle Clerk React.
+
+The page supports email and password (including password reset), Google OAuth, and discoverable passkeys. Methods render in the order supplied. After Clerk authenticates the browser, Phoenix exchanges the short-lived Clerk session token for the normal one-time authorization code and session without reloading the application. The existing server OAuth redirect remains the fallback if the in-place exchange cannot complete.
+
+## Enable Clerk
+
+Set `useClerk` in the application spec:
+
+```yaml
+# spec/application.yaml
+useAuthHook: true
+useClerk: true
+```
+
+`phoenix sync` then adds `@clerk/clerk-react` as a direct application dependency and generates typed Clerk environment readers. `phoenix deployment:prepare-local` writes the deployment's public `CLERK_PUBLISHABLE_KEY` to `.env.generated`; application source should read it from `phx.frontendEnv`, not hardcode a key.
+
+## Configure the auth webhook
+
+Add the Clerk session handler alongside the existing code and refresh handlers:
+
+```typescript
+const authHandler = phx.webhooks.authHandlerBuilder
+  .withClerkSessionHandler()
+  .withClerkCodeHandler()
+  .withClerkRefreshHandler()
+  .withAnonymousHandler(async () => ({ success: false }))
+  .build()
+
+export default phx.webhooks.webhookBuilder.withAuthHook(authHandler).build()
+```
+
+The generated webhook context supplies Clerk credentials plus both valid deployment origins: `FRONTEND_URL` for the hosted application and `RESOURCES_URL` for standalone Admin. The session handler verifies the token signature, issuer, expiry, session claims, and authorized origin, then loads the current Clerk user. Banned users are rejected before Phoenix mints a session. The Clerk user id identifies the session user as `clerk-<id>`, so a signed-in user keeps the same identity, such as the same assistant thread, across browsers; see [Session User](?path=/docs/phoenix-sessions-and-access--docs#session-user).
+
+## Add an Admin sign-in page
+
+Register `ClerkNotAuthorizedAdminPage` as the Admin fallback element:
+
+```tsx
+import { ClerkNotAuthorizedAdminPage } from '@salsita-ai/sdk/extras/clerk'
+
+export default phx.frontend.admin.createNotAuthorizedAdminPage(() => (
+  <ClerkNotAuthorizedAdminPage
+    clerkPublishableKey={phx.frontendEnv.CLERK_PUBLISHABLE_KEY}
+    environmentId={phx.frontendEnv.ENVIRONMENT_ID}
+    methods={['google', 'email-password', 'passkey']}
+  />
+))
+```
+
+Users with a plain `user` role see an access-denied page instead of the Admin application. They can sign out and switch accounts from there.
+The same page is also the default fallback when Admin session authentication fails, so existing Clerk registrations keep
+an inline sign-in path. Register `createNotAuthenticatedAdminPage` only when authentication errors need a different page.
+
+## Add a Configurator sign-in page
+
+Use `ClerkNotAuthenticatedPage` when the Configurator rejects anonymous sessions:
+
+```tsx
+import { ClerkNotAuthenticatedPage } from '@salsita-ai/sdk/extras/clerk'
+
+export default phx.frontend.createNotAuthenticatedPage(() => (
+  <ClerkNotAuthenticatedPage
+    clerkPublishableKey={phx.frontendEnv.CLERK_PUBLISHABLE_KEY}
+    environmentId={phx.frontendEnv.ENVIRONMENT_ID}
+    methods={['email-password', 'google']}
+  />
+))
+```
+
+`environmentId` enables the redirect-free exchange before a Phoenix session exists. If it is unavailable, the page uses the server OAuth redirect flow.
+
+## Lifecycle behavior
+
+- Returning from Google with the browser Back button restores the sign-in controls, including from the back-forward cache.
+- Explicit Phoenix logout also signs the browser out of Clerk. If Clerk sign-out fails, the page preserves logout intent and offers a retry instead of silently signing the user back in.
+- An existing Clerk browser session signs in automatically unless the page was reached through explicit logout.
+- The automatic exchange runs at most once per page load. If the deployment's auth webhook rejects the exchanged session, the page settles on an error state with a "Try again" button rather than exchanging again — one activation of the button makes exactly one new attempt. Reloading the page grants a fresh automatic attempt.
+- The inline Clerk session does not provide a Phoenix refresh token. When the Phoenix session expires, the page exchanges the still-active Clerk session again.
+
+For the broader session model, see [Sessions and Access](?path=/docs/phoenix-sessions-and-access--docs). For all webhook handler types and Clerk environment setup, see [Webhooks](?path=/docs/phoenix-webhooks--docs).