@hraness/slopcamera 3.2.4

package/docs/studio.md

@@ -0,0 +1,215 @@
+# Native film studio
+
+Slopcamera lets an agent retain a production scene, direct a native renderer, inspect its exact outputs and bring the result into an ordinary video project. Blender handles detailed 3D, CadQuery handles parametric solids and STEP, and Manim Community handles educational animation. Existing Three/Spark rendering, diagrams, image generation, narration, captions, effects and short-clip directing remain available in the same CLI.
+
+Native authoring preserves the engine's control. A Blender source can use armatures, skinning, IK, shape keys, geometry nodes, materials, lights, cameras and simulation caches. A CadQuery program preserves dimensions and solid operations. A Manim scene preserves mathematical objects and timing. Portable meshes and finished videos are derivatives; retain the native source when later edits require it.
+
+Use the [Slopcamera source installation](how-to/use-current-source.md) for the `studio` commands described here. Start with the [one-second native film tutorial](tutorials/first-native-film.md) for a bounded CPU shot, or use [educational animation with narration](how-to/educational-video.md) for Manim.
+
+## Make the first shot
+
+Install a supported engine yourself, or use an existing installation. Slopcamera does not silently install or upgrade native tools. The initial qualified versions are Blender 5.2.1 LTS, CadQuery 2.8.0 and Manim Community 0.21.0. Select the exact Blender executable or Python virtual environment for each invocation.
+
+```sh
+slopcamera studio init product --template blender-product --json
+slopcamera studio bundle product/source.json --json
+slopcamera studio plan product/job.json --json
+slopcamera studio probe product/job.json --blender-bin /Applications/Blender.app/Contents/MacOS/Blender --json
+slopcamera studio run product/job.json --blender-bin /Applications/Blender.app/Contents/MacOS/Blender --allow-trusted-code --json
+```
+
+The scaffold creates `scene.py`, any explicit helpers, `source.json` and `job.json`. Edit the source and job to direct the shot. After a source edit, run `studio bundle` again, copy the returned `bundleSha256` into the job and choose a new `jobId`. Reusing an old job ID with changed inputs is a conflict. `studio plan` parses and hashes the request without loading a native engine.
+
+The default Blender product job requests Cycles GPU rendering. An unavailable GPU fails clearly. Select `device: "cpu"` in a new job when CPU rendering is intended; no fallback is implicit. Initial Metal shader compilation can make the first render substantially slower than later frames.
+
+Other starters:
+
+```sh
+slopcamera studio init character --template blender-character
+slopcamera studio init city --template blender-shaded-street
+slopcamera studio init cloth --template blender-cloth
+slopcamera studio init liquid --template blender-fluid
+slopcamera studio init bracket --template cadquery-bracket
+slopcamera studio init lesson --template manim-lesson
+```
+
+Run CAD or Manim with `--python /absolute/path/to/venv/bin/python`. Preserve that virtual-environment path: resolving its interpreter symlink to a system Python can select the wrong package environment.
+
+The shaded-street starter provides an original city, a detailed native character and a calibrated three-second camera approach in 360×640 portrait. Set the render dimensions to 720×1280 for a larger output, select `shot: "speaker"` with no `motion` for a fixed presenter view, or use `motion: "return"` for the world-panel reveal. Native source and all helpers are included in the scaffold. The [hybrid scene example](../examples/studio/hybrid-scene.ts) uses the same panel dimensions and camera contract with Three.
+
+Set `panelTexture: "panel.png"` and include that opaque 9:16 PNG in `source.json` to reuse a finished Three frame or diagram on the native board. The starter packs its sRGB pixels into an unlit native surface at the shared world position; other geometry still occludes it. This is a baked image derivative. It preserves the depicted frame, while the original Three scene remains the source for editing its content.
+
+## Source and output contract
+
+`source.json` lists exactly the files to retain. Its paths are relative to the manifest's directory, or to an explicit `--source-root`. Imports do not recursively discover siblings, follow file symlinks or run Python.
+
+```json
+{
+  "engine": "blender",
+  "entrypoint": { "kind": "python", "path": "scene.py" },
+  "files": ["scene.py", "studio_scene.py", "models/product.glb", "textures/basecolor.png"]
+}
+```
+
+The host stores a content-addressed manifest and immutable file copies under `artifacts/slopcamera/private/studio/bundles/`. Jobs bind those retained bytes, typed engine settings, parameters, a stage, output declarations and limits. The source may execute at module scope or use the documented engine hooks. Blender and CadQuery support `build(context)`; an explicit bake job may call `bake(context)`. Manim selects a named scene class. See the checked examples for the exact hook contracts.
+
+`SLOPCAMERA_CONTEXT` supplies detached parameters, stage, render clock and the private source/output/working roots. Helpers and imported assets belong in the explicit bundle. Diagnostics and temporary files belong in the working root; only declared deliverables belong in the output root. The host rejects undeclared files, links, empty outputs, missing frames and exceeded limits.
+
+Frame intervals are half-open: `startFrame: 24, endFrameExclusive: 48` means 24 frames. Frame rate is a reduced rational numerator/denominator. Raster outputs declare channels, precision, color space, alpha and semantic meaning. Model outputs declare units, up axis and handedness. CadQuery's adapter explicitly converts its millimeter geometry into meter-scale, Y-up GLB; STEP remains millimeters and Z-up.
+
+Successful receipts include the exact source/job/plan/runtime identities and every physical output hash and length. Runtime identity records executable and driver hashes plus observed package/version evidence. It is not a hash of every system library, font, installed plugin or external read. Native source runs as the current user and the profile is explicitly nonhermetic.
+
+## Turn frames into a project clip
+
+```sh
+slopcamera studio encode <studio-id> --output-id beauty --json
+slopcamera studio assemble <studio-id> --output-id beauty --name "The first shot" --json
+```
+
+Encoding accepts a successfully receipted PNG color sequence and creates a separately retained derivative. RGB becomes lossless H.264 RGB MP4; straight RGBA becomes lossless QTRLE MOV. The encoder checks every decoded frame against its source pixels and checks the exact clock. Native movie validation currently admits observed 8-bit RGB/RGBA interpretations; higher-precision video profiles require separate qualification. A 16-bit PNG sequence produces an explicitly recorded 8-bit derivative without dithering; the original masters remain intact. Linear EXR and data passes need an explicit compositing/color pipeline before delivery and are not silently converted by this command.
+
+`studio assemble` reuses the verified encode and creates an ordinary video project with exact native/encode lineage. Its initial clip profile accepts opaque sRGB sequences up to 4096 pixels per side, 4000 frames and 60 seconds. Use `project add` for subsequent clips, narration and SFX, and `project render run` for delivery. Transparent sequences remain an explicit encode/overlay workflow.
+
+The returned artifact is an ordinary local media reference. A repeated encode verifies its source and derivative receipts instead of resubmitting a completed conversion. Retain transparent MOV or linear masters for compositing; make a normal SDR delivery through the project renderer when broad player compatibility matters.
+
+## Detailed assets, rigs and simulation
+
+The supported Poly Haven adapter searches and imports free HDRIs, selected PBR maps and glTF model dependencies. A selection chooses one asset, resolution and file format; the plan retains author, license, API credit, catalog bytes and the complete dependency list. Imports verify those bytes and retain SHA-256 identities. Powered by [Poly Haven](https://polyhaven.com/).
+
+```sh
+slopcamera studio assets search query.json --json
+slopcamera studio assets describe dirty_football --json
+slopcamera studio assets plan selection.json --json
+slopcamera studio assets import asset-plan.json --json
+```
+
+A search input is `{"provider":"poly-haven","query":"football","type":"models","limit":5}`. A model selection is `{"provider":"poly-haven","assetId":"dirty_football","resolution":"1k","kind":"model","format":"gltf"}`. Save the complete JSON plan returned by the plan command before importing it. The default total download bound is 50 MiB. Include the returned source files explicitly in a studio bundle; acquisition never executes or inserts an asset into a native scene. See the [asset adapter contract](../apps/desktop/studio/assets/README.md) for texture/HDRI selections, current terms and supported dependencies.
+
+Use Blender's native importers for supplied GLB/glTF, OBJ/MTL, FBX and other supported formats. Retain all required textures, buffers and animation files. `examples/studio/blender/import_model.py` and the CadQuery STEP example show explicit local-input routes. Native imports have a broader feature set tha Slopcamera's deliberately bounded portable GLB parser; an imported native control rig is not automatically editable through portable spatial patches.
+
+The original character example includes a deforming skeleton, blended weights, an IK target and facial shape keys. Keep control names and source parameters stable when directing later takes. Full upstream rigging APIs remain available to trusted authoring code, but arbitrary rig retargeting, production facial systems and third-party add-ons require their own setup and qualification.
+
+Cloth and fluid starters use separate bake and render stages. Retain the resulting `.blend` and explicit caches, then create a source bundle with the native scene and its dependencies for a render job. A `.blend` entrypoint supports rendering with embedded-script execution disabled; rebuilding, rebaking, Python-dependent rig drivers or add-on initialization require an explicit authored Python setup. Unpacked FILE images must be exact existing declared bundle files, or their bytes must be packed in the scene. Linked libraries, volumes and other dependencies still need their own explicit source closure and validation. Preserve the relative cache layout when moving a bundle. Rendering a completed cache should not recompute its solver or depend on frame visitation order.
+
+Physics settings are not proof of a bake. Review evaluated geometry, contact and cache evidence, then load the result in a fresh process. Cloth pins, collider thickness, object scale, time steps and warmup affect the image. Liquid surface and volume caches need explicit storage budgets. Keep native cache identity tied to the source and settings that produced it.
+
+## Share assets across renderers
+
+Keep each native source alongside its portable representations. Use `.blend` for the detailed character rig, cloth caches and procedural materials; use a validated static GLB for city geometry; use sRGB images and videos for finished diagrams, generated footage and graphics. A video displayed in a world-space plane can be occluded and filmed by another camera. Its pixels do not supply hidden geometry or new views of the depicted world.
+
+| Representation | Useful transfer | Boundary |
+| --- | --- | --- |
+| Native `.blend`, STEP and caches | Edit or rerender in the originating tool | Native rig controls, solids, solvers and procedural materials remain engine-specific |
+| Portable GLB | Share measured geometry, supported base-color materials and node TRS clips with Three | Admission rejects skins, morph targets and unsupported texture/material features; export an explicit compatible derivative |
+| sRGB PNG or retained RGB(A) video | Mount a diagram, avatar, generated shot or GPU graphic in either scene | Preserve pixel size, alpha, color interpretation and the exact source clock |
+| Splats | Film a captured appearance through the qualified Three/Spark profile | Appearance capture does not establish collision geometry, relighting or native mesh editability |
+
+Admit an existing native output with an explicit asset identity:
+
+```sh
+slopcamera studio asset studio_city --output-id city --asset-id asset_city --representation native --json
+slopcamera studio asset studio_shot --output-id beauty --asset-id asset_reference --representation native --frame 1 --json
+slopcamera studio encode studio_shot --output-id beauty --json
+slopcamera studio asset studio_shot --output-id beauty --asset-id asset_movie --representation encoded-video --json
+```
+
+The result contains an `asset`, a `binding`, and a retained admission `receipt`. Add the asset to the spatial scene and supply an array of bindings through `scene render --assets bindings.json`. The asset payload path is a logical locator; the binding selects the exact retained physical bytes. Admission verifies the native job, source lineage and supported representation without executing source or encoding again. A sequence needs an exact frame for image admission. Encoded-video admission requires one unambiguous completed `studio encode` derivative. Conflicting derivatives require explicit resolution; there is no implicit latest selection.
+
+Prepared GLB geometry travels as a hash-bound local JSON resource, with source interpretation and validated primitives retained in the render evidence. Vertex arrays do not inflate the HTML document. An explicit resource fetch flag admits only its exact private path; the host and browser both verify its bytes. Existing geometry, texture, frame and resource limits still apply. Detailed native meshes may need an explicit preview LOD; preserve its export settings and measured bounds alongside the native source.
+
+Blender owns full native scene production. Three owns Slopcamera's calibrated portable scene and world-space media composition. vgpu supplies programmable WebGPU passes. The [optional vgpu example](../examples/studio/vgpu/README.md) renders an exact-time graphic into retained raster frames for use on a world-space screen. It uses a separately provisioned runtime. It does not enable a second scene renderer or shared GPU textures inside Slopcamera's WebGL2/Spark profile. The upstream [Three integration](https://github.com/vercel-labs/vgpu/blob/main/docs/topics/threejs.docs.md) can expose WGSL functions as TSL nodes, but using that path requires a qualified Three WebGPU profile.
+
+## Exchange calibrated cameras
+
+Export one camera's evaluated poses and projection at a rational frame rate:
+
+```json
+{"cameraId":"camera_hero","startUs":0,"frameRate":{"numerator":24,"denominator":1},"frameCount":480}
+```
+
+Save that sampling request as `sampling.json`, then run:
+
+```sh
+slopcamera scene camera-track scene.json --request sampling.json --output camera-track.json --json
+```
+
+The inert `slopcamera.spatial-camera-track` document pins the scene revision and contains ordered `samples`, each with `frameIndex`, integer `timeUs`, exact rational `exactTimeUs`, and the existing `SpatialCamera` value. It preserves off-center principal points, unequal focal lengths, orthographic extents and the canonical Y-up meter basis. Export at most 2,048 frames per chunk within the 2 MiB JSON limit. Sampling uses the scene's half-open duration and independently rounds each exact sample once to microseconds.
+
+Retain this JSON in a native source bundle. The fixed Blender driver exposes `SLOPCAMERA_APPLY_SPATIAL_CAMERA(camera, camera_object=None)` to authored Python. It converts canonical `(x,y,z)` to Blender `(x,-z,y)` and preserves the camera's local negative-Z direction. Apply each sample explicitly at its associated native frame; do not interpolate a second time using an unrelated easing curve. A supplied camera must have no parent, constraints or animation owners. Unsupported native parameter ranges fail rather than silently changing framing. The helper does not exchange depth of field, distortion, shutter, lighting or color transforms.
+
+For a native animated camera, first calculate all requested poses on an unconstrained camera, then insert the saved poses as native keys. Calling the helper after adding an animation owner is rejected. A matching projection does not imply identical materials or lighting between renderers; use a shared raster surface when a cut must preserve finished pixels.
+
+## Lighting, camera and color
+
+The product source demonstrates beveled geometry, textured materials, glass, area lighting, a moving camera and depth of field. Native source can expose camera lens, focus, aperture, shutter and lighting parameters directly. Cycles and EEVEE have different rendering behavior; choosing EEVEE creates a different job and runtime profile.
+
+Blender review PNGs use the chosen view transform and sRGB display output. Linear EXR beauty uses Linear Rec.709 and the declared half/full floating-point precision. Transparent PNG is straight alpha; transparent EXR is premultiplied. Auxiliary depth, normal, mask or object-ID files remain explicitly authored compositor outputs with data-space semantics. The host checks actual EXR channel precision and framing and decodes output files; physical units and coordinate meaning still need correct source and fixture validation.
+
+Keep linear masters when grading or compositing requires them. Do not tone-map a review PNG a second time, apply a beauty transform to data passes or assume an exported GLB can reproduce arbitrary procedural materials. A splat capture describes observed appearance; it does not automatically provide editable objects, collision geometry or physically relightable materials.
+
+## Educational films and generated media
+
+The Manim starter produces a 10-second portrait example with an original Luma presenter, vector geometry, Typst mathematics, gestures and a caption rail. Its 3–4–5 construction rearranges nine plus sixteen equal-area tiles into a five-by-five square. This illustrates one Pythagoras example; it does not claim a general proof.
+
+`lesson.json` retains the script, cue timing, gestures, mouth shapes and mathematical parameters. Cue provenance distinguishes authored timing from measured word or mouth alignment. Word highlights use half-open microsecond intervals; a resting mouth fills gaps. Portrait margins reserve room for the presenter, diagram and captions rather than cropping a landscape composition blindly. See `examples/studio/education/README.md` for the lesson fields and the standalone source closure.
+
+Generate illustrations and narration through the existing Gateway operations, then retain their returned asset references:
+
+```sh
+slopcamera ai models list --type image --json
+slopcamera ai image generate --model <image-model> --prompt-file illustration.txt --json
+slopcamera ai models list --type speech --json
+slopcamera ai speech generate --model <speech-model> --text-file narration.txt --json
+```
+
+These generation commands can incur provider charges. Use the live catalog and existing explicit upload controls. Studio execution itself makes no paid model call. It neither receives provider credentials in its child environment nor automatically regenerates narration or images when a scene renders.
+
+Use `slopcamera diagram init|check|render` for structured diagrams, `slopcamera image vectorize` for local vectorization, existing transcription for measured captions, and ordinary audio/media operations for narration, music and SFX. Rhubarb mouth cues can be retained as measured performance input using the toolkit's conversion helper; mouth shapes are not word timestamps. A supplied or generated voice needs an actual listening/alignment review before authored cues can be described as synchronized speech.
+
+Ordinary project overlays interpret `--position x,y` as a pixel offset from the selected anchor. Use `--anchor center --position 0,0` to center an overlay, or `--anchor top-left --position 42,70 --width 636 --height 180` to place a caption inside a 720×1280 portrait frame with 42-pixel side margins. A full-frame closing image uses `--anchor top-left --position 0,0` with the output dimensions. Inspect the rendered caption bounds and closing frame before delivery.
+
+The Manim driver owns silent visuals and exact frames. It rejects source-side audio so the existing Slopcamera composition remains the audio owner. That separation lets an agent revise narration or sound independently while preserving the mathematical rendering and provider receipts.
+
+## Qualified profiles and extension limits
+
+Local acceptance used Blender 5.2.1 LTS on an Apple M4 Max, CadQuery 2.8.0 and Manim Community 0.21.0. These are measured fixtures, not a promise that every engine feature, device or imported asset behaves identically.
+
+| Capability | Checked behavior | Boundary |
+| --- | --- | --- |
+| Cycles / EEVEE | Actual Metal renders; product materials, moving camera and depth of field | Other GPU backends need their own qualification; GPU rendering does not imply GPU physics |
+| Character | Weighted mesh deformation, IK reach and facial shape keys survive native reload | Automatic production-rig retargeting is not supplied |
+| Cloth / liquid | Real caches, changed evaluated geometry and fresh-process replay; liquid cache relocation | Solver validity and portable determinism depend on the source and runtime |
+| CAD | Valid STEP round trip, preserved solid volume and measured meter/Y-up GLB bounds | Original third-party CAD feature history is not reconstructed |
+| Color | Half-float linear EXR, preserved HDR values, premultiplied EXR and straight PNG edges | Auxiliary pass units and coordinate meaning require fixture-specific validation |
+| Education | Portrait presenter, Typst mathematics, exact frame interval and transparent frame output | Authored cue timing is distinct from measured speech alignment |
+| Acquisition | Free Poly Haven HDRI and complete glTF dependency closure, verified offline replay | Other catalogs use authorized supplied files; no generic marketplace automation |
+
+Blender's native Python APIs can author Geometry Nodes, hair, volumes, additional solvers and compositor effects. Those APIs are available to trusted source; Slopcamera does not advertise each as a separately qualified automatic workflow. USD, Alembic and other interchange retain only the semantics their particular exporters support. Robotics or RL environments additionally need step/reset, state/action, sensor and physical validation contracts; a cinematic scene or splat capture alone does not supply those guarantees.
+
+## Use native jobs in an agent workflow
+
+The checked `examples/studio/native-workflow.ts` accepts `{bundle: {path: "<retained manifest>"}, job: <job document>}` as its input JSON. The local declarative SDK exposes `.studio.run()` through `@hraness/slopcamera/local/code`. Its closed operation is `slopcamera.studio.run`. Inputs refer to the retained bundle manifest and a parsed studio job; planning binds the installed runtime under normal host admission. Outputs are ordinary hash-bound media references and a studio receipt, ready for subsequent retained media operations.
+
+```sh
+slopcamera code run film.ts --input input.json --studio-python /absolute/venv/bin/python --allow-trusted-code --json
+slopcamera runs resume <run-id> --studio-python /absolute/venv/bin/python --allow-trusted-code --json
+```
+
+The same runtime/authorization flags are available on `workflows run`. Runtime selection alone does not authorize source execution. A missing native trust envelope pauses the node before dispatch; adding the explicit flag on resume permits the exact bound plan. Generic stored write approval cannot grant native code permission. Changing a runtime, source or job after binding requires a compatible new plan.
+
+Use the source-backed Bun package for `code` workflows and local SDK imports. The copied macOS executable supports direct `studio` commands with embedded starters and drivers; its older workflow build-identity scanner still requires the installed source distribution.
+
+Native results can be imported into ordinary Slopcamera projects with their declared video/audio roles. The existing V2 spatial renderer still has its qualified Three-specific rendering path; attaching a native candidate does not make that path consume it. Preserve a native shot's source and receipt alongside its ordinary project media derivative.
+
+## Inspection and recovery
+
+```sh
+slopcamera studio inspect <studio-id> --json
+slopcamera studio reconcile <studio-id> --json
+```
+
+Inspection rechecks source and physical output hashes. Reconciliation can restore a missing receipt only when a closed successful process completion and an unchanged output-validation checkpoint exist. Earlier interrupted execution remains ambiguous and is never automatically resubmitted. Choose a new job ID for an explicitly revised attempt after custody is settled.
+
+The supervisor bounds combined logs, the job deadline and termination/pipe-drain grace. It monitors output and scratch budgets, retains failure evidence and tracks native process groups. Live scans tolerate bounded disappearance of temporary cache entries; final output, source and scratch scans remain strict. Budget-monitor and validation failures retain a safe failed host stage separately from authored-process logs, without storing foreign exception text. A machine-wide durable activity marker survives CLI death; unresolved custody blocks later native dispatch. Detached sessions from authored source are unsupported. Do not delete an unresolved marker to bypass admission; inspect and resolve the actual process ownership first.
+
+The native profile is trusted current-user execution without an OS sandbox. Private roots, clean environment variables, hashes and process supervision provide operational control and provenance. They do not confine arbitrary Python, installed plugins or native libraries. Keep unreviewed downloaded source inert until execution is explicitly authorized.

package/examples/studio/blender/README.md

@@ -0,0 +1,26 @@
+# Authored Blender studio examples
+
+These examples use Blender's native Python APIs through SLOPCAMERA's explicitly trusted source-bundle workflow. Include the selected entrypoint and `studio_scene.py` as declared bundle files. Imported assets and their dependencies must also be declared. The scripts do not download anything or use a provider.
+
+| Entrypoint | Features | Initial qualification job |
+| --- | --- | --- |
+| `product.py` | Machined metal, glass, fine surface detail, key/fill/rim lighting, camera move and focus pull | Render frames `[1,25)` at 24fps; start at 320×180/16 samples, then select 960×540/64-sample review frames |
+| `character.py` | Weighted continuous arm, IK goal and pole, articulated skeleton, blink/smile/jaw shape keys | Render `[1,25)` at 24fps; compare frames 1, 9, 18 and 24 |
+| `import_model.py` | Standard GLB, glTF or OBJ/MTL import, measured bounds, framed camera and lighting | Parameter `input` names a declared relative asset path; optional `environment` names a retained linear Rec.709 HDR/EXR; loaded images are packed into the native scene |
+| `cloth.py` | Cloth dynamics, collision, woven shading, completed native point cache and Alembic deformation export | Bake with native `native/scene.blend` and directory `cache/cloth`; subsequently render the retained `.blend` at frame 32 |
+| `fluid.py` | Mantaflow liquid volume, collision basin, meshed splash, retained simulation data and surface cache | Bake with native `native/scene.blend` and directory `cache/fluid`; subsequently render the retained `.blend` around frames 12–24 |
+| `color_chart.py` | Known linear emission patches, including values above one, against a transparent background | One frame with denoising disabled, explicit RGBA PNG/straight and half-float EXR/premultiplied declarations; compare decoded center values and alpha |
+
+Simulation scripts define `build(context)` and `bake(context)`. The fixed driver executes the Python module, calls `build` when present, saves the declared native scene, and calls `bake` only for a bake job. A render job never implicitly calls `bake`. Fluid resolution defaults to 24 and is bounded to 16–48 in this fixture. Cloth uses 40 simulation frames and fluid uses 32. Cloth defaults to a free drape; parameter `pinBackCorners: true` adds two fully weighted pin vertices and verifies that their evaluated positions remain fixed throughout the completed bake. The cache evidence JSON records evaluated geometry after the real bake; it is not a substitute for inspecting rendered images or reloading the cache.
+
+For native-source render jobs, make a new source bundle containing the retained `.blend` and its complete explicitly declared cache/input tree. Preserve the relative layout. The fluid example stores its cache path relative to the native scene. The cloth scene retains the completed point cache in its `.blend` and additionally publishes an Alembic deformation cache.
+
+For `.blend` entrypoints, unpacked `FILE` images must resolve to exact physical files declared inside the source bundle; otherwise the driver fails before rendering. Packing image bytes avoids ambient original paths. The import example packs all imported file images, including HDR environments that Blender has not yet decoded. Broader native dependencies, such as linked libraries, sequences, volumes and arbitrary authored handlers, still require explicit source management and feature-specific qualification; this check does not claim a complete hermetic Blender dependency graph.
+
+The driver supports automatic beauty PNG/EXR files or frame sequences and GLB/USD model exports. An image sequence uses exactly one `%06d` token and the job's half-open frame interval. A beauty file requires one frame. Use SLOPCAMERA's ordinary retained media pipeline for video encoding. Authored Python may use Blender's full compositor API to write separately declared auxiliary outputs.
+
+Automatic PNG beauty declares sRGB, RGB/opaque or RGBA/straight alpha, uint8 or uint16, color semantic and unitless units. Automatic EXR beauty declares linear Rec.709, float16 or float32, RGB/opaque or RGBA/premultiplied alpha. The driver sets output conversion explicitly and reports the source working space. GLB output declares meters, right-handed Y-up; USD output requires a meter-scale scene and declares right-handed Z-up.
+
+`SLOPCAMERA_CONTEXT` contains `parameters`, `stage`, `render`, `sourceRoot`, `outputRoot`, and `workingRoot`. Paths are absolute retained roots. The object is detached from the driver's admitted job. The driver and source run as the current user; hashes and declared outputs provide identity and verification, not an operating-system sandbox or hermetic execution.
+
+Capability qualification should record native Blender build/device logs, exact source and output hashes, full pixel decoding, selected-frame contact sheets, and observed runtime/storage. A configured feature is not yet a qualified feature. GPU selection uses native Cycles discovery and rejects an unavailable requested GPU instead of silently selecting CPU. EEVEE requires an explicit GPU request.

package/examples/studio/blender/character.py

@@ -0,0 +1,152 @@
+"""An articulated studio character with a skinned IK arm and blended facial shapes."""
+
+import math
+import bpy
+from studio_scene import reset, material, cube, cylinder, sphere, camera, floor, studio_lights
+
+
+def weighted(obj, armature, weights):
+    modifier = obj.modifiers.new("Character skin", "ARMATURE")
+    modifier.object = armature
+    obj.parent = armature
+    for bone_name, vertex_weights in weights.items():
+        group = obj.vertex_groups.new(name=bone_name)
+        for index, weight in vertex_weights:
+            if weight > 0:
+                group.add([index], weight, "REPLACE")
+
+
+def rigid_skin(obj, armature, bone_name):
+    weighted(obj, armature, {bone_name: [(v.index, 1) for v in obj.data.vertices]})
+
+
+def build(context):
+    scene = reset()
+    ceramic = material("Warm porcelain shell", (0.69, 0.75, 0.73), roughness=0.26)
+    teal = material("Teal woven joint sleeve", (0.027, 0.23, 0.28), roughness=0.5, texture=True)
+    dark = material("Graphite facial details", (0.012, 0.027, 0.037), roughness=0.30)
+    copper = material("Copper joint collars", (0.56, 0.19, 0.065), metallic=0.82, roughness=0.3)
+    floor(size=25)
+    skeleton = bpy.data.armatures.new("Character deformation skeleton")
+    rig = bpy.data.objects.new("Character rig", skeleton)
+    bpy.context.collection.objects.link(rig)
+    bpy.context.view_layer.objects.active = rig
+    rig.select_set(True)
+    bpy.ops.object.mode_set(mode="EDIT")
+    definitions = [
+        ("root", (0, 0, 0.1), (0, 0, 0.65), None),
+        ("chest", (0, 0, 0.65), (0, 0, 1.20), "root"),
+        ("head", (0, 0, 1.20), (0, 0, 1.67), "chest"),
+        ("upper_arm.R", (0.29, 0, 1.15), (0.61, 0, 1.12), "chest"),
+        ("forearm.R", (0.61, 0, 1.12), (0.91, 0, 1.09), "upper_arm.R"),
+        ("upper_arm.L", (-0.29, 0, 1.15), (-0.42, 0, 0.85), "chest"),
+        ("forearm.L", (-0.42, 0, 0.85), (-0.43, -0.025, 0.58), "upper_arm.L"),
+        ("leg.R", (0.14, 0, 0.65), (0.14, 0, 0.14), "root"),
+        ("leg.L", (-0.14, 0, 0.65), (-0.14, 0, 0.14), "root"),
+    ]
+    for name, head, tail, parent in definitions:
+        bone = skeleton.edit_bones.new(name)
+        bone.head, bone.tail = head, tail
+        if parent:
+            bone.parent = skeleton.edit_bones[parent]
+    bpy.ops.object.mode_set(mode="OBJECT")
+    torso = sphere("Porcelain torso", (0, 0, 0.96), (0.29, 0.16, 0.36), ceramic)
+    rigid_skin(torso, rig, "chest")
+    head = sphere("Expressive head", (0, -0.012, 1.47), (0.275, 0.19, 0.245), ceramic)
+    rigid_skin(head, rig, "head")
+    head.shape_key_add(name="Basis")
+    jaw = head.shape_key_add(name="JawOpen")
+    for vertex in jaw.data:
+        if vertex.co.z < -0.02:
+            vertex.co.z -= 0.055 * min(1, -vertex.co.z / 0.18)
+    for side, x in (("L", -0.095), ("R", 0.095)):
+        eye = sphere("Eye." + side, (x, -0.190, 1.51), (0.038, 0.014, 0.053), dark)
+        rigid_skin(eye, rig, "head")
+        eye.shape_key_add(name="Basis")
+        blink = eye.shape_key_add(name="Blink")
+        for vertex in blink.data:
+            vertex.co.z *= 0.12
+        for frame, value in ((1, 0), (7, 0), (9, 1), (11, 0), (24, 0)):
+            blink.value = value
+            blink.keyframe_insert("value", frame=frame)
+    vertices, faces = [], []
+    for index in range(25):
+        x = (index / 24 - 0.5) * 0.17
+        for offset in (-0.007, 0.007):
+            vertices.append((x, -0.202, 1.40 + offset))
+        if index:
+            faces.append((2 * index - 2, 2 * index, 2 * index + 1, 2 * index - 1))
+    mesh = bpy.data.meshes.new("Mouth surface")
+    mesh.from_pydata(vertices, [], faces)
+    mouth = bpy.data.objects.new("Animated smile", mesh)
+    bpy.context.collection.objects.link(mouth)
+    mouth.data.materials.append(dark)
+    rigid_skin(mouth, rig, "head")
+    mouth.shape_key_add(name="Basis")
+    smile = mouth.shape_key_add(name="Smile")
+    open_mouth = mouth.shape_key_add(name="MouthOpen")
+    for index, vertex in enumerate(smile.data):
+        vertex.co.z += 0.055 * (abs(vertex.co.x) / 0.085) ** 1.7
+    for index, vertex in enumerate(open_mouth.data):
+        vertex.co.z += (0.018 if index % 2 else -0.018) * (1 - (vertex.co.x / 0.09) ** 2)
+    for frame, value in ((1, 0.1), (12, 0.3), (18, 1), (24, 0.85)):
+        smile.value = value
+        smile.keyframe_insert("value", frame=frame)
+    for frame, value in ((1, 0), (12, 0.1), (17, 0.8), (21, 0.2), (24, 0)):
+        open_mouth.value = value
+        open_mouth.keyframe_insert("value", frame=frame)
+        jaw.value = value
+        jaw.keyframe_insert("value", frame=frame)
+    # Continuous tube with blended weights demonstrates skin deformation at the elbow.
+    vertices, faces, weights = [], [], {"upper_arm.R": [], "forearm.R": []}
+    for ring in range(25):
+        x = 0.29 + ring / 24 * 0.62
+        z = 1.15 - ring / 24 * 0.06
+        blend = max(0, min(1, (x - 0.55) / 0.12))
+        for radial in range(16):
+            angle = radial * math.tau / 16
+            index = len(vertices)
+            vertices.append((x, math.cos(angle) * 0.073, z + math.sin(angle) * 0.073))
+            weights["upper_arm.R"].append((index, 1 - blend))
+            weights["forearm.R"].append((index, blend))
+            if ring:
+                previous = (radial + 1) % 16
+                faces.append(((ring - 1) * 16 + radial, (ring - 1) * 16 + previous,
+                              ring * 16 + previous, ring * 16 + radial))
+    mesh = bpy.data.meshes.new("Continuous arm skin")
+    mesh.from_pydata(vertices, [], faces)
+    arm = bpy.data.objects.new("Deforming IK sleeve", mesh)
+    bpy.context.collection.objects.link(arm)
+    arm.data.materials.append(teal)
+    for polygon in mesh.polygons:
+        polygon.use_smooth = True
+    weighted(arm, rig, weights)
+    hand = sphere("Reaching hand", (0.94, 0, 1.09), (0.105, 0.085, 0.085), ceramic)
+    rigid_skin(hand, rig, "forearm.R")
+    for side, x in (("L", -0.14), ("R", 0.14)):
+        leg = cylinder("Leg." + side, (x, 0, 0.40), 0.10, 0.40, teal, 0.025)
+        rigid_skin(leg, rig, "leg." + side)
+        foot = sphere("Foot." + side, (x, -0.065, 0.11), (0.135, 0.19, 0.09), ceramic)
+        rigid_skin(foot, rig, "leg." + side)
+    left_arm = sphere("Left arm sleeve", (-0.39, 0, 0.91), (0.08, 0.085, 0.23), teal)
+    rigid_skin(left_arm, rig, "upper_arm.L")
+    left_hand = sphere("Left hand", (-0.43, -0.025, 0.58), (0.09, 0.085, 0.10), ceramic)
+    rigid_skin(left_hand, rig, "forearm.L")
+    for x in (-0.27, 0.27):
+        sphere("Shoulder collar", (x, 0, 1.15), (0.095, 0.10, 0.10), copper)
+    goal = bpy.data.objects.new("Right hand IK goal", None)
+    bpy.context.collection.objects.link(goal)
+    goal.empty_display_type = "SPHERE"
+    goal.empty_display_size = 0.05
+    for frame, location in ((1, (0.88, 0, 1.09)), (12, (0.69, -0.10, 1.45)),
+                            (18, (0.62, -0.09, 1.59)), (24, (0.73, -0.08, 1.48))):
+        goal.location = location
+        goal.keyframe_insert("location", frame=frame)
+    pole = bpy.data.objects.new("Elbow pole", None)
+    bpy.context.collection.objects.link(pole)
+    pole.location = (0.6, -0.7, 0.8)
+    ik = rig.pose.bones["forearm.R"].constraints.new("IK")
+    ik.target, ik.pole_target, ik.chain_count, ik.use_stretch = goal, pole, 2, False
+    studio_lights(scale=1)
+    camera((2.4, -4.4, 2.1), (0.12, 0, 0.87), lens=47, fstop=8)
+    scene.frame_set((context.get("render") or {}).get("startFrame", 1))

package/examples/studio/blender/cloth.py

@@ -0,0 +1,101 @@
+"""Bake a woven cloth over a rounded pedestal; render its retained native scene."""
+
+import json
+from pathlib import Path
+import bpy
+from studio_scene import reset, material, cube, sphere, camera, floor, studio_lights
+
+
+def build(context):
+    scene = reset()
+    floor(size=15)
+    pedestal = sphere("Cloth collision pedestal", (0, 0, 0.53), (0.40, 0.38, 0.43),
+                      material("Porcelain pedestal", (0.58, 0.63, 0.59), roughness=0.28))
+    pedestal.modifiers.new("Cloth collider", "COLLISION")
+    pedestal.collision.thickness_outer = 0.015
+    bpy.ops.mesh.primitive_grid_add(x_subdivisions=33, y_subdivisions=33, size=1.6, location=(0, 0, 1.12))
+    cloth = bpy.context.object
+    cloth.name = "Woven cloth"
+    cloth.data.materials.append(material("Copper velvet weave", (0.38, 0.10, 0.025), roughness=0.64, texture=True))
+    for polygon in cloth.data.polygons:
+        polygon.use_smooth = True
+    modifier = cloth.modifiers.new("Authored cloth solver", "CLOTH")
+    modifier.settings.quality = 6
+    modifier.settings.mass = 0.3
+    modifier.settings.tension_stiffness = 18
+    modifier.settings.compression_stiffness = 18
+    modifier.settings.shear_stiffness = 8
+    modifier.settings.bending_stiffness = 0.4
+    modifier.collision_settings.use_collision = True
+    modifier.collision_settings.distance_min = 0.012
+    modifier.collision_settings.use_self_collision = True
+    modifier.collision_settings.self_distance_min = 0.012
+    modifier.point_cache.frame_start = 1
+    modifier.point_cache.frame_end = 40
+    modifier.point_cache.use_disk_cache = False
+    if context["parameters"].get("pinBackCorners", False):
+        pins = [vertex.index for vertex in cloth.data.vertices if vertex.co.y > 0.79 and abs(vertex.co.x) > 0.79]
+        if len(pins) != 2:
+            raise RuntimeError("Expected exactly two authored back-corner pin vertices")
+        group = cloth.vertex_groups.new(name="Pinned back corners")
+        group.add(pins, 1.0, "REPLACE")
+        modifier.settings.vertex_group_mass = group.name
+        modifier.settings.pin_stiffness = 1.0
+    solidify = cloth.modifiers.new("Fabric thickness", "SOLIDIFY")
+    solidify.thickness = 0.005
+    subdivision = cloth.modifiers.new("Fabric finish", "SUBSURF")
+    subdivision.levels = 1
+    subdivision.render_levels = 1
+    studio_lights(scale=0.8)
+    camera((2.3, -2.8, 2.05), (0, 0, 0.62), lens=55, fstop=8)
+    scene.frame_start, scene.frame_end = 1, 40
+    scene.frame_set(1)
+
+
+def bake(context):
+    scene = bpy.context.scene
+    cloth = bpy.data.objects["Woven cloth"]
+    cache = cloth.modifiers["Authored cloth solver"].point_cache
+    bpy.context.view_layer.objects.active = cloth
+    with bpy.context.temp_override(scene=scene, active_object=cloth, object=cloth, point_cache=cache):
+        bpy.ops.ptcache.bake(bake=True)
+    if not cache.is_baked:
+        raise RuntimeError("Cloth solver did not produce a completed bake")
+    cache_root = Path(context["outputRoot"]) / "cache" / "cloth"
+    cache_root.mkdir(parents=True, exist_ok=True)
+    facts = []
+    for frame in (1, 16, 32, 40):
+        scene.frame_set(frame)
+        evaluated = cloth.evaluated_get(bpy.context.evaluated_depsgraph_get())
+        mesh = evaluated.to_mesh()
+        facts.append({"frame": frame, "vertices": len(mesh.vertices),
+                      "minZ": min((evaluated.matrix_world @ v.co).z for v in mesh.vertices),
+                      "maxZ": max((evaluated.matrix_world @ v.co).z for v in mesh.vertices)})
+        evaluated.to_mesh_clear()
+    # Portable deformation cache supplements the native .blend's baked point cache.
+    bpy.ops.object.select_all(action="DESELECT")
+    cloth.select_set(True)
+    bpy.ops.wm.alembic_export(filepath=str(cache_root / "cloth.abc"), start=1, end=40,
+                              selected=True, xsamples=1, gsamples=1, check_existing=False)
+    pin_facts = []
+    pin_group = cloth.vertex_groups.get("Pinned back corners")
+    if pin_group:
+        indices = [vertex.index for vertex in cloth.data.vertices if any(group.group == pin_group.index and group.weight == 1 for group in vertex.groups)]
+        finish = [modifier for modifier in cloth.modifiers if modifier.type in ("SOLIDIFY", "SUBSURF")]
+        flags = [modifier.show_viewport for modifier in finish]
+        try:
+            for modifier in finish:
+                modifier.show_viewport = False
+            for frame in range(1, 41):
+                scene.frame_set(frame)
+                evaluated = cloth.evaluated_get(bpy.context.evaluated_depsgraph_get())
+                mesh = evaluated.to_mesh()
+                pin_facts.append({"frame": frame, "positions": [list(evaluated.matrix_world @ mesh.vertices[index].co) for index in indices]})
+                evaluated.to_mesh_clear()
+            if any(abs(a - b) > 0.000001 for fact in pin_facts[1:] for first, current in zip(pin_facts[0]["positions"], fact["positions"]) for a, b in zip(first, current)):
+                raise RuntimeError("Completed cloth bake moved a fully weighted pin vertex")
+        finally:
+            for modifier, flag in zip(finish, flags):
+                modifier.show_viewport = flag
+    (cache_root / "bake-evidence.json").write_text(json.dumps({"isBaked": cache.is_baked, "frames": facts, "pins": pin_facts}, indent=2) + "\n")
+    scene.frame_set(32)

package/examples/studio/blender/color_chart.py

@@ -0,0 +1,29 @@
+"""Known linear-emission patches for PNG/EXR color and alpha qualification."""
+
+import bpy
+from studio_scene import reset, camera
+
+
+def build(context):
+    scene = reset()
+    scene.world.node_tree.nodes["Background"].inputs["Strength"].default_value = 0
+    colors = ((0.18, 0.18, 0.18), (1, 0, 0), (0, 1, 0),
+              (0, 0, 1), (2, 1, 0.5), (0.5, 0.25, 0.125))
+    for index, color in enumerate(colors):
+        bpy.ops.mesh.primitive_plane_add(size=1, location=((index % 3 - 1), 0.4 if index < 3 else -0.4, 0))
+        patch = bpy.context.object
+        patch.name = "Linear emission patch " + str(index)
+        patch.scale = (0.8, 0.55, 1)
+        material = bpy.data.materials.new(patch.name)
+        material.use_nodes = True
+        material.node_tree.nodes.clear()
+        emission = material.node_tree.nodes.new("ShaderNodeEmission")
+        emission.inputs["Color"].default_value = (*color, 1)
+        emission.inputs["Strength"].default_value = 1
+        output = material.node_tree.nodes.new("ShaderNodeOutputMaterial")
+        material.node_tree.links.new(emission.outputs["Emission"], output.inputs["Surface"])
+        patch.data.materials.append(material)
+    shot = camera((0, 0, 4), (0, 0, 0))
+    shot.data.type = "ORTHO"
+    shot.data.ortho_scale = 3.2
+    shot.data.dof.use_dof = False

package/examples/studio/blender/fluid.py

@@ -0,0 +1,78 @@
+"""Small liquid splash with an explicit Mantaflow bake and retained cache."""
+
+import json
+import os
+from pathlib import Path
+import bpy
+from studio_scene import reset, material, cube, sphere, camera, floor, studio_lights
+
+
+def build(context):
+    scene = reset()
+    floor(size=15)
+    stone = material("Basin ceramic", (0.18, 0.26, 0.28), roughness=0.24)
+    for name, center, size in (
+        ("Basin bottom", (0, 0, 0.05), (1.3, 1.1, 0.10)),
+        ("Basin back", (0, 0.52, 0.18), (1.3, 0.10, 0.30)),
+        ("Basin front", (0, -0.52, 0.14), (1.3, 0.10, 0.22)),
+        ("Basin left", (-0.60, 0, 0.18), (0.10, 1.0, 0.30)),
+        ("Basin right", (0.60, 0, 0.18), (0.10, 1.0, 0.30)),
+    ):
+        wall = cube(name, center, size, stone, 0.02)
+        modifier = wall.modifiers.new("Liquid collision", "FLUID")
+        modifier.fluid_type = "EFFECTOR"
+        modifier.effector_settings.surface_distance = 0.001
+    liquid = material("Clear turquoise water", (0.25, 0.70, 0.74), roughness=0.09, transmission=0.88)
+    domain = cube("Liquid domain", (0, 0, 0.66), (1.45, 1.25, 1.35), liquid)
+    modifier = domain.modifiers.new("Authored liquid solver", "FLUID")
+    modifier.fluid_type = "DOMAIN"
+    settings = modifier.domain_settings
+    settings.domain_type = "LIQUID"
+    settings.resolution_max = int(context["parameters"].get("resolution", 24))
+    if not 16 <= settings.resolution_max <= 48:
+        raise ValueError("Fluid fixture resolution must stay between 16 and 48")
+    settings.cache_frame_start = 1
+    settings.cache_frame_end = 32
+    settings.cache_type = "ALL"
+    settings.cache_directory = str(Path(context["outputRoot"]) / "cache" / "fluid")
+    settings.cache_data_format = "UNI"
+    settings.use_mesh = True
+    settings.mesh_scale = 2
+    settings.timesteps_min = 1
+    settings.timesteps_max = 4
+    source = sphere("Initial liquid volume", (0, 0, 0.89), (0.30, 0.30, 0.27), liquid)
+    source.hide_render = True
+    flow = source.modifiers.new("Liquid source", "FLUID")
+    flow.fluid_type = "FLOW"
+    flow.flow_settings.flow_type = "LIQUID"
+    flow.flow_settings.flow_behavior = "GEOMETRY"
+    studio_lights(scale=0.8)
+    camera((2.3, -2.7, 1.9), (0, 0, 0.35), lens=55, fstop=8)
+    scene.frame_start, scene.frame_end = 1, 32
+    scene.frame_set(1)
+
+
+def bake(context):
+    scene = bpy.context.scene
+    domain = bpy.data.objects["Liquid domain"]
+    settings = domain.modifiers["Authored liquid solver"].domain_settings
+    bpy.context.view_layer.objects.active = domain
+    bpy.ops.object.select_all(action="DESELECT")
+    domain.select_set(True)
+    with bpy.context.temp_override(scene=scene, active_object=domain, object=domain):
+        bpy.ops.fluid.bake_all()
+    if not settings.has_cache_baked_data or not settings.has_cache_baked_mesh:
+        raise RuntimeError("Liquid solver did not complete data and surface-mesh bakes")
+    facts = []
+    for frame in (1, 12, 24, 32):
+        scene.frame_set(frame)
+        evaluated = domain.evaluated_get(bpy.context.evaluated_depsgraph_get())
+        mesh = evaluated.to_mesh()
+        facts.append({"frame": frame, "vertices": len(mesh.vertices), "polygons": len(mesh.polygons)})
+        evaluated.to_mesh_clear()
+    cache_root = Path(context["outputRoot"]) / "cache" / "fluid"
+    (cache_root / "bake-evidence.json").write_text(json.dumps({"dataBaked": True, "meshBaked": True, "frames": facts}, indent=2) + "\n")
+    # The native scene stays movable with its declared cache dependency tree.
+    if bpy.data.filepath:
+        settings.cache_directory = "//" + os.path.relpath(cache_root, Path(bpy.data.filepath).parent)
+    scene.frame_set(24)