@hraness/slopcamera 3.2.4

package/examples/studio/blender/studio_scene.py

@@ -0,0 +1,147 @@
+"""Small authored scene helpers; include this exact file in the source bundle."""
+
+import math
+import bpy
+from mathutils import Vector
+
+
+def reset():
+    bpy.ops.object.select_all(action="SELECT")
+    bpy.ops.object.delete(use_global=False)
+    scene = bpy.context.scene
+    scene.unit_settings.system = "METRIC"
+    scene.unit_settings.scale_length = 1.0
+    scene.world = bpy.data.worlds.new("Studio environment")
+    scene.world.use_nodes = True
+    scene.world.node_tree.nodes["Background"].inputs["Color"].default_value = (0.055, 0.075, 0.12, 1)
+    scene.world.node_tree.nodes["Background"].inputs["Strength"].default_value = 0.24
+    scene.render.image_settings.color_mode = "RGB"
+    scene.view_settings.look = "AgX - Medium High Contrast"
+    return scene
+
+
+def material(name, color, metallic=0.0, roughness=0.35, transmission=0.0, texture=False):
+    mat = bpy.data.materials.new(name)
+    mat.diffuse_color = (*color, 1)
+    mat.use_nodes = True
+    nodes = mat.node_tree.nodes
+    shader = nodes.get("Principled BSDF")
+    shader.inputs["Base Color"].default_value = (*color, 1)
+    shader.inputs["Metallic"].default_value = metallic
+    shader.inputs["Roughness"].default_value = roughness
+    shader.inputs["Transmission Weight"].default_value = transmission
+    shader.inputs["IOR"].default_value = 1.46
+    if texture:
+        noise = nodes.new("ShaderNodeTexNoise")
+        noise.inputs["Scale"].default_value = 180
+        noise.inputs["Detail"].default_value = 2
+        bump = nodes.new("ShaderNodeBump")
+        bump.inputs["Strength"].default_value = 0.16
+        bump.inputs["Distance"].default_value = 0.001
+        mat.node_tree.links.new(noise.outputs["Fac"], bump.inputs["Height"])
+        mat.node_tree.links.new(bump.outputs["Normal"], shader.inputs["Normal"])
+    return mat
+
+
+def finish(obj, name, mat, bevel=0.0, smooth=True):
+    obj.name = name
+    if mat:
+        obj.data.materials.append(mat)
+    if bevel:
+        modifier = obj.modifiers.new("Machined edge radius", "BEVEL")
+        modifier.width = bevel
+        modifier.segments = 3
+    if smooth and obj.type == "MESH":
+        for polygon in obj.data.polygons:
+            polygon.use_smooth = True
+    return obj
+
+
+def cube(name, location, scale, mat, bevel=0.0):
+    bpy.ops.mesh.primitive_cube_add(size=1, location=location)
+    obj = bpy.context.object
+    obj.scale = scale
+    bpy.ops.object.transform_apply(location=False, rotation=False, scale=True)
+    return finish(obj, name, mat, bevel, False)
+
+
+def sphere(name, location, scale, mat, segments=48):
+    bpy.ops.mesh.primitive_uv_sphere_add(segments=segments, ring_count=24, radius=1, location=location)
+    obj = bpy.context.object
+    obj.scale = scale
+    bpy.ops.object.transform_apply(location=False, rotation=False, scale=True)
+    return finish(obj, name, mat)
+
+
+def cylinder(name, location, radius, depth, mat, bevel=0.0, rotation=(0, 0, 0), vertices=64):
+    bpy.ops.mesh.primitive_cylinder_add(vertices=vertices, radius=radius, depth=depth,
+                                      location=location, rotation=rotation)
+    return finish(bpy.context.object, name, mat, bevel)
+
+
+def torus(name, location, major, minor, mat, rotation=(0, 0, 0)):
+    bpy.ops.mesh.primitive_torus_add(major_segments=72, minor_segments=12, major_radius=major,
+                                   minor_radius=minor, location=location, rotation=rotation)
+    return finish(bpy.context.object, name, mat)
+
+
+def aim(obj, target):
+    obj.rotation_euler = (Vector(target) - obj.location).to_track_quat("-Z", "Y").to_euler()
+
+
+def area(name, location, target, energy, color, size, size_y=None):
+    data = bpy.data.lights.new(name, "AREA")
+    data.energy = energy
+    data.color = color
+    data.shape = "RECTANGLE"
+    data.size = size
+    data.size_y = size_y if size_y else size
+    obj = bpy.data.objects.new(name, data)
+    bpy.context.collection.objects.link(obj)
+    obj.location = location
+    aim(obj, target)
+    return obj
+
+
+def camera(location, target, lens=55, fstop=4.0):
+    data = bpy.data.cameras.new("Cinema camera")
+    data.lens = lens
+    data.sensor_width = 36
+    data.clip_start = 0.005
+    data.clip_end = 100
+    data.dof.use_dof = True
+    data.dof.aperture_fstop = fstop
+    data.dof.aperture_blades = 8
+    obj = bpy.data.objects.new("Cinema camera", data)
+    bpy.context.collection.objects.link(obj)
+    obj.location = location
+    aim(obj, target)
+    data.dof.focus_distance = (Vector(target) - obj.location).length
+    bpy.context.scene.camera = obj
+    return obj
+
+
+def floor(size=200, z=0, color=(0.055, 0.075, 0.10)):
+    return cube("Seamless studio floor", (0, 0, z - 0.02), (size, size, 0.04),
+                material("Slate studio floor", color, roughness=0.45), 0.01)
+
+
+def studio_lights(scale=1):
+    area("Warm softbox", (-2 * scale, -2 * scale, 3 * scale), (0, 0, scale),
+         300 * scale * scale, (1.0, 0.82, 0.62), 2 * scale)
+    area("Cool edge strip", (2 * scale, scale, 2.2 * scale), (0, 0, scale),
+         420 * scale * scale, (0.45, 0.68, 1.0), 0.45 * scale, 2 * scale)
+    area("Front fill", (0, -3 * scale, 1.5 * scale), (0, 0, scale),
+         90 * scale * scale, (0.8, 0.9, 1), 2 * scale)
+
+
+def set_linear_animation(obj):
+    if obj.animation_data and obj.animation_data.action:
+        for slot in obj.animation_data.action.slots:
+            for layer in obj.animation_data.action.layers:
+                for strip in layer.strips:
+                    bag = strip.channelbag(slot)
+                    if bag:
+                        for curve in bag.fcurves:
+                            for key in curve.keyframe_points:
+                                key.interpolation = "LINEAR"

package/examples/studio/cadquery/README.md

@@ -0,0 +1,13 @@
+# Authored CAD studio examples
+
+`bracket.py` builds a parametric millimeter-scale instrument mount with counterbored mounting holes, an upright circular aperture, fillets, and a separate isolation pad. Its `build(context)` hook returns a CadQuery `Assembly`; the driver uses that return value as the configured `exportVariable`.
+
+`import_step.py` imports an exact caller-declared STEP dependency, defaulting to `assets/bracket.step`. It preserves the assembly import surface supported by the installed CadQuery reader. STEP is the resulting CAD solid/assembly; the Python source retains the editable feature program.
+
+Use a build job with STEP and GLB file outputs. Automatic native CAD geometry uses millimeters and right-handed Z-up. STEP output must declare that space; standard GLB output must declare meters and right-handed Y-up. The driver records solid validity, volume, bounds, face/solid counts, and tessellation settings. STEP uses CadQuery's assembly writer. GLB uses CadQuery's colored assembly conversion with OCCT's explicit unit and coordinate-system converter: input 0.001 meters per unit, output one meter per unit, Z-up to Y-up. This conversion includes mesh positions and assembly transforms; CadQuery 2.8's high-level GLB writer alone leaves numeric millimeters unchanged.
+
+Parameters for the bracket are `widthMm` (default 100), `depthMm` (64), `heightMm` (56), and `thicknessMm` (8). Optional `rootTranslationMm` and `rootRotationDegrees` exercise translated and Z-rotated assemblies. The fixture bounds each parameter. A practical initial mesh tolerance is 0.1mm with angular tolerance 0.1 radians. Inspect GLB vertex bounds and complete node transforms after conversion; the existence of a file does not establish correct scale.
+
+To photograph the generated GLB, include it in a new Blender source bundle with `import_model.py` and `studio_scene.py`. This separates exact CAD source, tessellated delivery geometry, and the cinematic scene while keeping their source identities available for review.
+
+IGES is not exposed by this high-level CadQuery adapter. Additional OCCT/FreeCAD ingestion is a separate future qualified capability. The driver does not install packages, download assets, accept arbitrary executable arguments, or silently repair failed CAD geometry.

package/examples/studio/cadquery/bracket.py

@@ -0,0 +1,36 @@
+"""Parametric instrument mount in millimeters; exports an editable solid assembly."""
+
+import cadquery as cq
+
+
+def build(context):
+    parameters = context["parameters"]
+    width = float(parameters.get("widthMm", 100))
+    depth = float(parameters.get("depthMm", 64))
+    height = float(parameters.get("heightMm", 56))
+    thickness = float(parameters.get("thicknessMm", 8))
+    if not (50 <= width <= 160 and 40 <= depth <= 100 and 30 <= height <= 100 and 5 <= thickness <= 12):
+        raise ValueError("Fixture dimensions exceed the qualified instrument-mount range")
+    base = cq.Workplane("XY").box(width, depth, thickness).edges("|Z").fillet(5)
+    base = base.faces(">Z").workplane().pushPoints([(-width / 2 + 14, -depth / 2 + 12),
+                                                  (width / 2 - 14, -depth / 2 + 12),
+                                                  (-width / 2 + 14, depth / 2 - 12),
+                                                  (width / 2 - 14, depth / 2 - 12)]).cboreHole(6, 11, 3)
+    upright = (cq.Workplane("XY").box(width - 22, thickness, height).edges("|Z").fillet(2)
+               .translate((0, depth / 2 - thickness / 2, height / 2 + thickness / 2)))
+    # Round each primitive before union: the union also contains the already
+    # rounded base and counterbores, whose vertical seam edges cannot be filleted.
+    body = base.union(upright)
+    # Cylindrical aperture runs through the vertical mounting plate.
+    aperture = cq.Workplane("XZ").center(0, height * 0.60).circle(12).extrude(depth, both=True)
+    body = body.cut(aperture)
+    assembly = cq.Assembly(name="InstrumentMount")
+    assembly.add(body, name="MachinedBracket", color=cq.Color(0.70, 0.45, 0.16))
+    pad = cq.Workplane("XY").box(width - 32, depth - 28, 2).translate((0, -3, thickness / 2 + 1))
+    assembly.add(pad, name="IsolationPad", color=cq.Color(0.04, 0.055, 0.07))
+    translation = parameters.get("rootTranslationMm", [0, 0, 0])
+    rotation = float(parameters.get("rootRotationDegrees", 0))
+    if len(translation) != 3 or any(abs(float(value)) > 1000 for value in translation) or not -180 <= rotation <= 180:
+        raise ValueError("Fixture root transform exceeds its qualified range")
+    assembly.loc = cq.Location(tuple(float(value) for value in translation), (0, 0, 1), rotation)
+    return assembly

package/examples/studio/cadquery/import_step.py

@@ -0,0 +1,12 @@
+"""Import a caller-declared STEP assembly; its exact bytes belong in the bundle."""
+
+from pathlib import Path
+import cadquery as cq
+
+
+def build(context):
+    relative = context["parameters"].get("input", "assets/bracket.step")
+    path = (Path(context["sourceRoot"]) / relative).resolve(strict=True)
+    if not path.is_relative_to(Path(context["sourceRoot"]).resolve()):
+        raise ValueError("STEP fixture input must be inside the retained source bundle")
+    return cq.Assembly.importStep(str(path), unit="MM")

package/examples/studio/education/README.md

@@ -0,0 +1,46 @@
+# A narrated geometry lesson
+
+This example renders a ten-second portrait Manim scene. Luma, an original copper lantern robot, points to a right triangle while 25 unit tiles rearrange into a five-by-five square. The final formula uses Manim Community's Typst renderer. The example demonstrates the 3–4–5 triangle; it does not prove Pythagoras for arbitrary triangles.
+
+## Author the retained lesson
+
+`lesson.json` contains the mathematical parameters, presentation text, cue times, and timing provenance. Times are integer microseconds. Caption words, mouth shapes, and gestures use half-open intervals; gaps between mouth cues select the resting mouth.
+
+The checked example has authored caption and mouth timings. These timings are a creative draft, not measured speech alignment. The complete narration script is:
+
+> A right triangle. Three up, four across. Square both legs: nine plus sixteen. That's twenty-five. So the long side is five.
+
+Use `parameters.lessonFile: "lesson.json"`, or supply the same validated data in `parameters.lesson`. The supported tile template takes two integer legs, each at most 12, with an integer hypotenuse at most 15. All displayed triangle lengths, square counts, and tile destinations derive from those values. Other explanations use an explicitly trusted Python scene with the reusable presenter, caption rail, `math_label`, and timing helpers.
+
+Include exactly these source files in the retained bundle:
+
+| Bundle path | Source |
+| --- | --- |
+| `scene.py` | This example's explicit entrypoint |
+| `lesson.json` | This example's retained lesson |
+| `lesson.py` | `apps/desktop/studio/education/lesson.py` |
+| `toolkit.py` | `apps/desktop/studio/education/toolkit.py` |
+
+The host records each file's bytes and digest. The fixed driver is separate from the author bundle. Importing or planning a bundle does not execute these files. Rendering runs explicitly trusted current-user Python; it is not a security sandbox or a hermetic build.
+
+## Render the scene
+
+Select Manim Community 0.21 with its Typst optional dependency, the Cairo renderer, `scene: "PythagoreanLesson"`, and `transparent: false`. The sample uses 480×854, 24/1 FPS, and frames `[0, 240)`. The reusable layout supports portrait aspect ratios from 0.48 through 0.75 and fits its title, panel, presenter, and captions inside the camera.
+
+Declare `beauty` PNG frames at `frames/%06d.png` and/or one opaque MP4 at `lesson.mp4`. PNG still output captures the last frame in the requested interval. Frame numbers retain the requested native indices; movie PTS starts at zero at the same exact rational cadence. Output interpretation is sRGB, uint8, RGB, opaque, color, unitless. Transparent rendering requires PNG with RGBA and straight alpha. The MP4 uses lossless RGB encoding so ordinary project assembly can avoid an extra chroma conversion during handoff.
+
+The driver profile supports up to 2048 pixels per dimension, four megapixels, 60 FPS, and intervals ending by frame 14,400. It checks the declared output byte and file limits, and the host independently checks physical outputs and decoded media. Cairo is a CPU profile. The driver does not claim GPU rendering or generate audio.
+
+## Bind narration, sound effects, and delivery captions
+
+The optional narration shape is `{"assetId":"voice_luma","transcript":"..."}`. Sound effects use `{"assetId":"tile_click","atUs":7600000,"gainDb":-18}`. These are inert references to existing retained SLOPCAMERA assets; the host verifies the source bytes and places audio in the ordinary project clock. The Manim driver never resolves credentials, synthesizes speech, or fetches an asset.
+
+For measured mouth movement, run Rhubarb on the exact retained WAV/OGG and import its JSON with `rhubarb_mouth_cues`. Retain the original cue receipt and recognizer identity with the audio, set `mouthTiming: "rhubarb"`, and retain the returned microsecond cues in the lesson. The converter discards absolute `soundFile` metadata and rejects overlap, nonfinite timestamps, or cues outside the lesson. Rhubarb mouth shapes are not word alignment; supply measured word timings separately before setting `captionTiming: "aligned"`.
+
+Set `showCaptions: false` when the ordinary project caption layer owns visible delivery captions. Keep the same retained word timings so the delivery can preserve exact emphasis without rendering captions twice. Review actual frames and the assembled voice together before claiming lip-sync quality.
+
+## Focused checks
+
+`python -B -m unittest discover -s apps/desktop/studio/education -p 'test_*.py'` runs pure parser, geometry, timing, profile, and path tests without importing Manim. Native qualification is a separate admitted host run and must inspect the actual decoded frames, exact cadence, text margins, triangle/tile geometry, and narration synchronization.
+
+The opt-in `apps/desktop/studio/education/qualify_native.py --output <fresh-absolute-directory>` runs static-frame, rational-cadence, alpha, short-scene, byte-budget, and portrait fixtures with the invoking Python runtime. It retains source manifests, jobs, logs, per-file digests, decoded PNG/MP4 pixel comparisons, and a contact sheet. Its observation file is explicitly separate from the host's authoritative studio receipt. Run it through the repository's native-work admission process.

package/examples/studio/education/lesson.json

@@ -0,0 +1,99 @@
+{
+  "kind": "slopcamera.education-lesson",
+  "schemaVersion": 1,
+  "title": "Why the long side is five",
+  "subtitle": "A 3–4–5 right triangle, one square at a time",
+  "durationUs": 10000000,
+  "topic": { "kind": "pythagorean-tiles", "legs": [3, 4] },
+  "beats": { "squaresUs": 3200000, "rearrangeUs": 5300000, "resultUs": 7600000 },
+  "presenter": { "name": "Luma" },
+  "captionTiming": "authored",
+  "mouthTiming": "authored",
+  "showCaptions": true,
+  "captions": [
+    { "words": [
+      { "text": "A", "startUs": 150000, "endUs": 290000 },
+      { "text": "right", "startUs": 290000, "endUs": 650000 },
+      { "text": "triangle.", "startUs": 650000, "endUs": 1150000 }
+    ] },
+    { "words": [
+      { "text": "Three", "startUs": 1250000, "endUs": 1680000 },
+      { "text": "up,", "startUs": 1680000, "endUs": 1940000 },
+      { "text": "four", "startUs": 2110000, "endUs": 2490000 },
+      { "text": "across.", "startUs": 2490000, "endUs": 3050000 }
+    ] },
+    { "words": [
+      { "text": "Square", "startUs": 3200000, "endUs": 3630000 },
+      { "text": "both", "startUs": 3630000, "endUs": 3940000 },
+      { "text": "legs:", "startUs": 3940000, "endUs": 4350000 }
+    ] },
+    { "words": [
+      { "text": "nine", "startUs": 4460000, "endUs": 4860000 },
+      { "text": "plus", "startUs": 4860000, "endUs": 5150000 },
+      { "text": "sixteen.", "startUs": 5150000, "endUs": 5820000 }
+    ] },
+    { "words": [
+      { "text": "That’s", "startUs": 6090000, "endUs": 6480000 },
+      { "text": "twenty-five.", "startUs": 6480000, "endUs": 7390000 }
+    ] },
+    { "words": [
+      { "text": "So", "startUs": 7690000, "endUs": 7910000 },
+      { "text": "the", "startUs": 7910000, "endUs": 8130000 },
+      { "text": "long", "startUs": 8130000, "endUs": 8530000 },
+      { "text": "side", "startUs": 8530000, "endUs": 8890000 },
+      { "text": "is", "startUs": 8890000, "endUs": 9090000 },
+      { "text": "five.", "startUs": 9090000, "endUs": 9740000 }
+    ] }
+  ],
+  "mouthCues": [
+    { "startUs": 150000, "endUs": 290000, "value": "C" },
+    { "startUs": 290000, "endUs": 650000, "value": "E" },
+    { "startUs": 650000, "endUs": 870000, "value": "D" },
+    { "startUs": 870000, "endUs": 1150000, "value": "H" },
+    { "startUs": 1250000, "endUs": 1490000, "value": "B" },
+    { "startUs": 1490000, "endUs": 1680000, "value": "C" },
+    { "startUs": 1680000, "endUs": 1940000, "value": "A" },
+    { "startUs": 2110000, "endUs": 2280000, "value": "G" },
+    { "startUs": 2280000, "endUs": 2490000, "value": "E" },
+    { "startUs": 2490000, "endUs": 2760000, "value": "D" },
+    { "startUs": 2760000, "endUs": 3050000, "value": "B" },
+    { "startUs": 3200000, "endUs": 3430000, "value": "F" },
+    { "startUs": 3430000, "endUs": 3630000, "value": "C" },
+    { "startUs": 3630000, "endUs": 3790000, "value": "A" },
+    { "startUs": 3790000, "endUs": 3940000, "value": "E" },
+    { "startUs": 3940000, "endUs": 4160000, "value": "H" },
+    { "startUs": 4160000, "endUs": 4350000, "value": "B" },
+    { "startUs": 4460000, "endUs": 4680000, "value": "D" },
+    { "startUs": 4680000, "endUs": 4860000, "value": "B" },
+    { "startUs": 4860000, "endUs": 5000000, "value": "A" },
+    { "startUs": 5000000, "endUs": 5150000, "value": "C" },
+    { "startUs": 5150000, "endUs": 5450000, "value": "B" },
+    { "startUs": 5450000, "endUs": 5660000, "value": "C" },
+    { "startUs": 5660000, "endUs": 5820000, "value": "B" },
+    { "startUs": 6090000, "endUs": 6310000, "value": "D" },
+    { "startUs": 6310000, "endUs": 6480000, "value": "B" },
+    { "startUs": 6480000, "endUs": 6700000, "value": "F" },
+    { "startUs": 6700000, "endUs": 6990000, "value": "C" },
+    { "startUs": 6990000, "endUs": 7170000, "value": "G" },
+    { "startUs": 7170000, "endUs": 7390000, "value": "D" },
+    { "startUs": 7690000, "endUs": 7910000, "value": "F" },
+    { "startUs": 7910000, "endUs": 8130000, "value": "B" },
+    { "startUs": 8130000, "endUs": 8330000, "value": "H" },
+    { "startUs": 8330000, "endUs": 8530000, "value": "E" },
+    { "startUs": 8530000, "endUs": 8740000, "value": "D" },
+    { "startUs": 8740000, "endUs": 8890000, "value": "B" },
+    { "startUs": 8890000, "endUs": 9090000, "value": "C" },
+    { "startUs": 9090000, "endUs": 9290000, "value": "G" },
+    { "startUs": 9290000, "endUs": 9510000, "value": "D" },
+    { "startUs": 9510000, "endUs": 9740000, "value": "G" }
+  ],
+  "gestures": [
+    { "startUs": 150000, "endUs": 1150000, "kind": "open" },
+    { "startUs": 1250000, "endUs": 3050000, "kind": "point" },
+    { "startUs": 3200000, "endUs": 4350000, "kind": "open" },
+    { "startUs": 4460000, "endUs": 5820000, "kind": "point" },
+    { "startUs": 6090000, "endUs": 7390000, "kind": "nod" },
+    { "startUs": 7690000, "endUs": 9740000, "kind": "point" }
+  ],
+  "sfx": []
+}

package/examples/studio/education/scene.py

@@ -0,0 +1,7 @@
+"""An explicitly trusted author entrypoint, evaluated only by a render job."""
+
+from toolkit import EducationalScene, lesson_from_context
+
+
+class PythagoreanLesson(EducationalScene):
+    lesson_data = lesson_from_context(SLOPCAMERA_CONTEXT)

package/examples/studio/hybrid-scene.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import {
+  parseSpatialScene, parseSpatialValue, SpatialAssetIdSchema, SpatialAssetManifestSchema, SpatialCameraSchema, SpatialPayloadSchema,
+  type SpatialSceneV1,
+} from "@hraness/slopcamera/code";
+
+/** Retained manifests and explicit host bindings; importing this authoring example is inert. */
+const boundAssetSchema = z.strictObject({
+  asset: SpatialAssetManifestSchema,
+  binding: z.strictObject({ assetId: SpatialAssetIdSchema, artifact: SpatialPayloadSchema }),
+}).refine(value => value.asset.assetId === value.binding.assetId && value.asset.payload.sha256 === value.binding.artifact.sha256
+  && value.asset.payload.bytes === value.binding.artifact.bytes, "Asset binding must identify its exact retained payload.");
+const inputSchema = z.strictObject({
+  panel: boundAssetSchema, font: boundAssetSchema, city: boundAssetSchema.optional(),
+  camera: SpatialCameraSchema.optional(), motion: z.enum(["locked", "reveal", "portal-loop"]).default("reveal"),
+  durationUs: z.number().int().min(1).max(4_000_000).default(4_000_000),
+});
+export type HybridWorldSceneInput = z.input<typeof inputSchema>;
+export const HYBRID_PANEL = Object.freeze({ center: Object.freeze([2.3, 1.47, -0.837] as const), width: 1.35, height: 2.4 });
+export const HYBRID_PANEL_CAMERA = SpatialCameraSchema.parse({ cameraId: "camera_panel", name: "Calibrated world panel",
+  pose: { position: [2.3, 1.47, 1.2255], rotation: [0,0,0,1] },
+  projection: { kind: "perspective", width: 720, height: 1280, fx: 1100, fy: 1100, cx: 360, cy: 640, near: 0.03, far: 100 } });
+Object.freeze(HYBRID_PANEL_CAMERA.pose.position); Object.freeze(HYBRID_PANEL_CAMERA.pose.rotation);
+Object.freeze(HYBRID_PANEL_CAMERA.pose); Object.freeze(HYBRID_PANEL_CAMERA.projection); Object.freeze(HYBRID_PANEL_CAMERA);
+const common = { parentId: null, placement: { kind: "world" }, origin: { kind: "authored" }, visible: true };
+const transform = (position: readonly number[]) => ({ position: [...position], rotation: [0,0,0,1], scale: [1,1,1] });
+const unlit = (color: string) => ({ kind: "unlit", color, opacity: 1 });
+function lookAt(position: number[], target: readonly number[]) {
+  const x = position[0]! - target[0]!, y = position[1]! - target[1]!, z = position[2]! - target[2]!;
+  const yaw = Math.atan2(x,z) / 2, pitch = -Math.atan2(y,Math.hypot(x,z)) / 2;
+  return { position, rotation: [Math.cos(yaw)*Math.sin(pitch), Math.sin(yaw)*Math.cos(pitch), -Math.sin(yaw)*Math.sin(pitch), Math.cos(yaw)*Math.cos(pitch)] };
+}
+
+/** One four-second explanation lives on a real plane in the same meter-based city. */
+export function createHybridWorldScene(input: unknown): {
+  readonly scene: SpatialSceneV1; readonly bindings: readonly z.infer<typeof boundAssetSchema>["binding"][];
+} {
+  const value = parseSpatialValue(inputSchema, input, "hybrid world scene"), camera = value.camera ?? HYBRID_PANEL_CAMERA;
+  const panel = value.panel.asset.interpretation, font = value.font.asset.interpretation;
+  if (panel.kind !== "video" && panel.kind !== "image" && panel.kind !== "diagram") throw new Error("Panel requires explicit video, image or diagram media.");
+  if (panel.kind === "video" && panel.durationUs < value.durationUs) throw new Error("Panel video must cover the complete authored segment; no implicit looping.");
+  if (font.kind !== "font" || font.format !== "otf") throw new Error("The example requires a declared OTF font.");
+  if (value.city && (value.city.asset.interpretation.kind !== "gltf" || value.city.asset.interpretation.format !== "glb")) throw new Error("City requires an admitted GLB profile.");
+  const x = HYBRID_PANEL.center[0], y = HYBRID_PANEL.center[1], z = HYBRID_PANEL.center[2];
+  const box = (id: string, name: string, position: number[], size: number[], color: string) => ({ ...common,
+    entityId: `entity_${id}`, kind: "mesh", name, geometry: { kind: "box", size }, material: unlit(color), transform: transform(position) });
+  const label = (id: string, text: string, atY: number, fontSize: number, color: string) => ({ ...common,
+    entityId: `entity_${id}`, kind: "text", name: text, fontAssetId: value.font.asset.assetId, text, fontSize, width: 1.12, color, align: "center", transform: transform([x,atY,z+0.016]) });
+  const entities: unknown[] = [
+    // All surfaces are world-space. The copper frame and foreground post have
+    // actual thickness; a later camera move can reveal and occlude their edges.
+    box("panel_back", "Midnight panel matte", [x,y,z-0.04], [1.44,2.49,0.07], "#091723"),
+    box("panel_left", "Copper left edge", [x-0.71,y,z+0.005], [0.035,2.51,0.10], "#bf8a56"),
+    box("panel_right", "Copper right edge", [x+0.71,y,z+0.005], [0.035,2.51,0.10], "#bf8a56"),
+    box("panel_top", "Copper top edge", [x,y+1.25,z+0.005], [1.455,0.035,0.10], "#ddba7c"),
+    box("panel_bottom", "Copper bottom edge", [x,y-1.25,z+0.005], [1.455,0.035,0.10], "#9b683f"),
+    { ...common, entityId: "entity_panel_media", kind: panel.kind, name: "Retained explanation in world space", assetId: value.panel.asset.assetId,
+      width: 1.26, height: 0.70875, fit: "contain", opacity: 1, transform: transform([x,y+0.02,z+0.013]),
+      ...(panel.kind === "video" ? { sourceOffsetUs: 0, playback: "once" } : {}) },
+    label("eyebrow", "DESIGN FOR SHADE", y+0.98, 0.063, "#80c6c3"),
+    label("title", "FOLLOW THE LIGHT", y+0.76, 0.095, "#f2eee3"),
+    label("caption", "Shade intercepts sunlight.", y-0.64, 0.058, "#d5e5de"),
+    label("note", "An illustrative energy split", y-0.80, 0.046, "#83a4ad"),
+    label("footer", "SUNLIGHT  /  SHADE  /  COMFORT", y-1.08, 0.034, "#809399"),
+    box("depth_post", "Foreground copper depth cue", [x+0.70,y-0.21,z+0.50], [0.048,2.32,0.065], "#7f573a"),
+    { ...common, entityId: "entity_ambient", kind: "light", name: "Soft sky", light: "ambient", color: "#d5e6ef", intensity: 1.3, transform: transform([0,0,0]) },
+    { ...common, entityId: "entity_sun", kind: "light", name: "Warm afternoon", light: "directional", color: "#ffe0b0", intensity: 2.4,
+      transform: { ...transform([5,8,5]), ...lookAt([5,8,5],[0,0,0]) } },
+    box("sky", "Warm blue horizon", [0,10,-50], [150,100,0.10], "#acbec0"),
+  ];
+  if (value.city) entities.push({ ...common, entityId: "entity_shared_city", kind: "mesh", name: "Retained native city preview LOD",
+    geometry: { kind: "asset", assetId: value.city.asset.assetId, materialMode: "source" }, material: unlit("#ffffff"), transform: transform([0,0,0]) });
+  else entities.push(box("ground", "Qualification ground", [0,-0.04,0], [80,0.08,80], "#d0cabd"));
+  const assets = [value.panel,value.font,...(value.city ? [value.city] : [])];
+  // A portal loop returns to the exact authored pose for a match cut into a
+  // native shot; its final five percent is a held camera, never extrapolation.
+  // Dense bounded keys preserve the eased turn instead of reversing velocity
+  // abruptly at a sparse peak. They still evaluate solely from absolute time.
+  const fractions = Array.from({ length: 41 }, (_, index) => index/40);
+  const times = [...new Set(fractions.map(t => Math.round(t*value.durationUs)))];
+  const poses = times.map(timeUs => {
+    const t = timeUs/value.durationUs;
+    const progress = value.motion === "portal-loop" ? t <= 0.55 ? (t-0.25)/0.30 : (0.95-t)/0.40 : (t-0.25)/0.75;
+    const u = Math.max(0,Math.min(1,progress));
+    const ease = u*u*(3-2*u);
+    const start = camera.pose.position, end = [4.5,2.7,4.4];
+    return ease === 0 ? camera.pose : lookAt(start.map((n,i) => n+(end[i]!-n)*ease), [x-0.35*ease,y+0.1*ease,z]);
+  });
+  const animations = value.motion === "locked" ? [] : [
+    { channelId: "channel_reveal_position", targetId: camera.cameraId, property: "position", interpolation: "linear", keys: times.map((timeUs,i) => ({ timeUs,value: poses[i]!.position })) },
+    { channelId: "channel_reveal_rotation", targetId: camera.cameraId, property: "rotation", interpolation: "slerp", keys: times.map((timeUs,i) => ({ timeUs,value: poses[i]!.rotation })) },
+  ];
+  const scene = parseSpatialScene({ kind: "slopcamera.spatial-scene", schemaVersion: 1, sceneId: "scene_hybrid_world_explainer", coordinates: "right-handed-y-up-meters",
+    durationUs: value.durationUs, cameras: [camera], assets: assets.map(item => item.asset), entities, animations, generators: [], overrides: [] });
+  return { scene, bindings: assets.map(item => item.binding) };
+}

package/examples/studio/native-workflow.ts

@@ -0,0 +1,14 @@
+import { defineWorkflow, StudioRunInputSchema } from "@hraness/slopcamera/local/code";
+
+// Input retains the bundle manifest returned by `studio bundle` and its exact job.
+// Runtime selection and --allow-trusted-code belong to the CLI invocation.
+export default defineWorkflow({
+  id: "native-studio-shot",
+  version: 1,
+  inputSchemaId: "native-studio-shot-input-v1",
+  inputSchema: StudioRunInputSchema,
+  build(workflow, input) {
+    const shot = workflow.studio.run("produce-shot", input);
+    return { shot };
+  },
+});

package/examples/studio/vgpu/README.md

@@ -0,0 +1,64 @@
+# Render an energy-flow panel with vgpu
+
+This example renders an animated diagram on a Metal GPU, then saves an opaque sRGB PNG sequence for an existing scene renderer to use as a screen surface. The energy split is authored illustrative data. The pulses and colored glazing explain the graphic; they are not a thermal simulation or measured performance.
+
+The example runs as an explicit trusted Node command. Importing its module does not load vgpu, execute a shader or acquire a GPU. It does not add a new SLOPCAMERA scene engine, a provider client or an editor. SLOPCAMERA's existing Three.js renderer can retain scene and camera ownership when consuming the resulting media.
+
+## Provision a separate runtime
+
+Use Node 24 on macOS for the qualified profile. Upstream vgpu documents Node 22+; other runtimes and GPU backends require separate qualification. Keep these dependencies in a dedicated directory outside tracked source:
+
+```json
+{
+  "name": "slopcamera-vgpu-example-runtime",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "vgpu": "0.4.1",
+    "pngjs": "7.0.0"
+  }
+}
+```
+
+In that directory, generate a lockfile and install with lifecycle execution disabled:
+
+```sh
+npm install --package-lock-only --ignore-scripts
+npm ci --ignore-scripts
+```
+
+The pinned vgpu adapter uses `webgpu@0.4.0`, which includes native Dawn binaries. Its macOS install hook normally modifies quarantine metadata, while vgpu's adapter hook may download a fallback binary. This example does not execute those hooks or modify platform security settings. Provision and review the native runtime separately if loading it fails.
+
+## Render
+
+Create the parent of the output directory first. The output directory itself must be new. Paths must be absolute and physical; the command preserves prior runs.
+
+```sh
+node /absolute/slopcamera/examples/studio/vgpu/heat-field.mjs \
+  --runtime /absolute/vgpu-runtime \
+  --output /absolute/retained-media/new-energy-panel
+```
+
+On Hraness hosts, wrap this native command with the installed `hra-host-run` in the `mac-native` lane. The default output is 96 frames at 24 fps, 768×432. Optional `--frames`, `--start-frame`, `--width` and `--height` values remain within a 16:9, 1024 px, 240-frame profile. A frame's shader time is its absolute frame number divided by 24; a selected nonzero interval retains that time while filenames begin at zero.
+
+Unset ambient `VGPU_*`, `NODE_OPTIONS` and `NODE_PATH` settings before invocation. The example rejects these overrides, explicitly requests Metal hardware, checks the observed hardware adapter and loaded native module, and records their identities. It permits no automatic CPU fallback as successful evidence.
+
+Each frame contains GPU-rendered pixels and original bitmap labels added after readback. Numerical energy quantities are separate from display colors. The shader performs the piecewise sRGB transfer; each PNG carries an explicit sRGB chunk. Calibration checks top-left row order, RGB channel order and an sRGB middle-gray value. Every retained PNG is decoded and compared with its source bytes.
+
+`manifest.json` records absolute times, runtime and native-binary hashes, shader/source/lock hashes, actual adapter identity, interpretation and frame digests. It appears after all frames verify and the GPU wrapper disposes. An incomplete directory has no completion manifest and remains available for diagnosis. This optional trusted runtime is not an OS sandbox or a hermetic dependency closure.
+
+The PNG files are ordinary media. Import them through a supported SLOPCAMERA media path with their manifest's frame cadence and sRGB interpretation; no vgpu object needs to cross into Three.js. Encoding them or admitting them to a native Studio job is a separate explicit action. The current native Studio adapters do not execute WGSL.
+
+## Check without a GPU
+
+Run these tests from a source checkout; the published package includes the example and this guide, but omits test files.
+
+```sh
+node --test examples/studio/vgpu/heat-field.test.mjs
+```
+
+These tests cover bounds, nonzero frame clocks, energy conservation, override rejection, authored layout and PNG tagging. They do not claim native shader execution. Actual hardware qualification must also inspect the retained frames.
+
+The September 9, 2026 qualification rendered 96 distinct frames on an Apple M4 Max with Metal 3 and Node 24.18.1. All PNG pixel comparisons and color/orientation calibration passed. Absolute frame 24 was identical when rendered in a fresh process alone, in a three-frame interval starting at 23, and in the full sequence starting at zero. That observation applies to this pinned runtime and device; it is not a cross-device bitwise guarantee.
+
+For future Three WebGPU work, vgpu provides a [WGSL-to-TSL bridge](https://github.com/vercel-labs/vgpu/blob/ca6cf99fbeb109a3294d043a10de16819e1b9dad/docs/topics/threejs.docs.md). That bridge leaves Three in charge of scenes and resources. It does not establish compatibility with SLOPCAMERA's current WebGL2/Spark profile. [Node runtime requirements](https://github.com/vercel-labs/vgpu/blob/ca6cf99fbeb109a3294d043a10de16819e1b9dad/packages/adapter-node/README.md).