dazpy 2.8.0__tar.gz → 2.9.3__tar.gz

{dazpy-2.8.0/dazpy.egg-info → dazpy-2.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dazpy
-Version: 2.8.0
+Version: 2.9.3
 Summary: Python SDK for the DAZ Studio Script Server
 License: MIT
 Project-URL: Homepage, https://github.com/bluemoonfoundry/daz-script-server
@@ -12,10 +12,12 @@ Requires-Dist: requests>=2.28
 Provides-Extra: docs
 Requires-Dist: sphinx>=7.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
+Provides-Extra: aio
+Requires-Dist: httpx>=0.24; extra == "aio"
 
 # DazScript Server
 
-**Version 2.8.0** | DAZ Studio 4.5+ | DAZ Studio 6.25+ | Windows & macOS
+**Version 2.9.3** | DAZ Studio 4.5+ | DAZ Studio 6.25+ | Windows & macOS
 
 [![Docs](https://img.shields.io/badge/docs-dazpy%20SDK-blue)](https://bluemoonfoundry.github.io/daz-script-server/)
 [![HTTP API](https://img.shields.io/badge/docs-HTTP%20API%20reference-blue)](https://bluemoonfoundry.github.io/daz-script-server/api-reference/)
@@ -78,11 +80,26 @@ print(response.json())
 
 ---
 
+## Examples
+
+**Complete example collection:** [daz-script-server-examples repository](https://github.com/bluemoonfoundry/daz-script-server-examples)
+
+Production-ready examples ranging from beginner tutorials to advanced pipeline implementations:
+- **48 examples** across 9 categories
+- Individual READMEs with skill level classification
+- Requirements.txt per example
+- Comprehensive searchable table
+
+Categories: fundamentals, character, animation, rendering, geometry, export, ml_data, ai_vision, bvh
+
+---
+
 ## 📋 Table of Contents
 
 ### Getting Started
 - [Quick Start](#-quick-start)
 - [Why This Exists](#why-this-exists)
+- [What's New in v2.9.0](#whats-new-in-v290)
 - [What's New in v2.8.0](#whats-new-in-v280)
 - [What's New in v2.7.2](#whats-new-in-v272)
 - [What's New in v2.7.1](#whats-new-in-v271)
@@ -170,6 +187,134 @@ DAZ Studio is powerful for 3D content creation, but automation is limited to man
 
 ---
 
+## What's New in v2.9.0
+
+### 🎬 dazpy.cinematics — camera shot builders
+
+`dazpy.cinematics` packages common camera choreography on top of
+`DazCamera`/`DazScene`: `apply_static_shot()` places/aims/configures a
+camera in one call; `apply_orbit_camera()` sweeps a camera around a target
+across a frame range; `apply_frame_subject()` frames a subject at a named
+shot distance (`close_up` / `medium` / `full_body`); and
+`apply_animated_shot()` writes real, interpolated DAZ Studio keyframes at a
+sequence of waypoints instead of baking a value on every frame.
+
+```python
+from dazpy.cinematics import OrbitCamera, apply_orbit_camera
+
+apply_orbit_camera(scene, OrbitCamera(target=figure, radius=250, frame_start=0, frame_end=90))
+```
+
+### 💡 dazpy.lighting — three-point rigs and HDRI environments
+
+`apply_three_point_light_setup()` creates and places a key/fill/rim light
+rig around a target in one call, via angle/distance placement or explicit
+world-space positions per light. `apply_hdri_environment()` applies
+image-based dome lighting — map, intensity, rotation, dome/scene mode,
+visibility, and IBL resolution — validating the image path up front and
+verifying a post-apply readback so a silent failure never passes as success.
+
+### 🧍 dazpy.poses — apply_pose, reset_transforms, zero_figure
+
+Common pose operations without hand-assembling a `DazPose`:
+`apply_pose()` applies a pose object or a JSON file path directly to a
+skeleton; `reset_transforms()` zeroes a node's local position/rotation and
+resets scale to 1.0; `zero_figure()` drives every bone rotation and morph
+to zero while leaving the figure's root transform untouched by default.
+
+### 📐 dazpy.math3.AxisRemap — coordinate-space conversion
+
+A generic signed-axis-permutation converter for `Vec3`/`Quat`/
+`BoundingBox` between coordinate conventions, with a ready-made
+`Y_UP_TO_Z_UP` preset for moving data from DAZ Studio (Y-up) into
+Blender/glTF-style Z-up pipelines.
+
+```python
+from dazpy.math3 import Y_UP_TO_Z_UP
+
+blender_pos = Y_UP_TO_Z_UP.apply_vec3(daz_pos)
+```
+
+### 🦴 DazSkeleton.bone_rotations_quat()
+
+Returns local-space quaternion rotations for every bone in one HTTP
+round-trip — the composable counterpart to `bone_rotations()` for callers
+feeding the result into another rotation (e.g. `AxisRemap.apply_quat()`),
+sidestepping the per-bone Euler rotation-order tracking that would
+otherwise be required.
+
+### 🎞️ Frame-level progress streaming for animation renders
+
+The `GET /render/:id/progress` SSE stream now emits a progress event at
+each frame boundary during an animation render, instead of only start/
+terminal events — the DAZ SDK exposes no per-percent render progress
+signal, so this frame-level marker is the most granular progress available.
+
+### ⚡ Async client — `dazpy.aio.AsyncDazClient`
+
+Async frameworks (FastAPI, FastMCP, ComfyUI custom nodes, asyncio/Temporal
+workflows) previously had to wrap every `DazClient` call in
+`asyncio.to_thread()` or hand-roll an `httpx.AsyncClient` wrapper.
+`dazpy.aio.AsyncDazClient` mirrors `DazClient`'s full method surface —
+`execute`, `execute_file`, inline/file async submit/status/result/list/cancel, render
+submit/batch/animation, USD export, and server-health endpoints — as
+native `async def` methods backed by `httpx.AsyncClient`, including the
+same `retry_on_busy`/`max_wait` backoff semantics (via `asyncio.sleep`
+instead of blocking `time.sleep`).
+
+```python
+from dazpy.aio import AsyncDazClient
+
+async def main():
+    async with AsyncDazClient() as client:
+        request_id = await client.execute_file_async_submit("C:/jobs/pose-probe.dsa")
+        result = await client.get_request_result(request_id, wait=True)
+        print(result)
+```
+
+Requires the optional `httpx` dependency: `pip install dazpy[aio]`.
+
+### `DazClient` connection pooling + `close()`
+
+`DazClient` now issues requests through a pooled `requests.Session` instead
+of a fresh connection per call, and supports `close()` / use as a context
+manager (`with DazClient() as client:`) for symmetry with the new async
+client's connection lifecycle.
+
+### Truthful Iray/Viewport render-engine selector
+
+`DazRenderSettings.render_engine_state()` now reads the effective
+`DzRenderOptions.renderType` value and the active renderer class/name as separate
+facts. Its schema-1 record includes the raw enum value/name, normalized
+`verified_iray` / `verified_non_iray` / `unavailable` status, and field-level
+live-readback provenance. A retained `NVIDIA Iray` active-renderer name never
+overrides a Viewport/OpenGL `renderType`.
+
+`DazRenderSettings.set_render_engine("iray" | "viewport")` is an explicit
+persistent setter. It selects the registered `DzIrayRenderer` plus `Software` for
+Iray, or `ScreenShot` for Viewport, calls `applyChanges()`, and returns only after
+exact readback. Missing renderers, mutation/apply faults, malformed replies, and
+readback disagreement raise `RenderError`; unknown engine names raise `ValueError`
+before dispatch.
+
+```python
+settings = DazRenderSettings(client)
+before = settings.render_engine_state()
+change = settings.set_render_engine("iray")
+assert change["readback"]["status"] == "verified_iray"
+```
+
+The `engine` field on `/render`, `/render/batch`, and `/render/animation` also
+accepts `viewport` and uses the same fail-closed mutation/readback rules. These
+operations intentionally persist the requested engine. DAZ documents `ScreenShot`
+and `HardwareAssisted` as Viewport/OpenGL operations and `Software` as the active
+software-renderer operation in the
+[DzRenderOptions reference](https://docs.daz3d.com/public/software/dazstudio/4/referenceguide/scripting/api_reference/object_index/renderoptions_dz);
+renderer lookup and activation are documented by
+[DzRenderMgr](https://docs.daz3d.com/public/software/dazstudio/4/referenceguide/scripting/api_reference/object_index/rendermgr_dz).
+
+---
+
 ## What's New in v2.8.0
 
 ### 🚦 Fail Fast When DAZ Studio Is Busy — `503 STUDIO_BUSY`
@@ -318,7 +463,7 @@ change.  For dirty scenes it serialises via `Scene.saveScene()` and restores
 the original filename immediately.  The `method` field in the response tells
 you which strategy was used.
 
-See `docs/examples/fundamentals/scene_save_copy.py` for a complete example
+See [`fundamentals/scene_save_copy`](https://github.com/bluemoonfoundry/daz-script-server-examples/tree/main/fundamentals/scene_save_copy) in the examples repo for a complete example
 with `--compare` and `--dry-run` options.
 
 ---
@@ -370,7 +515,7 @@ snapshot  = scene.scene_snapshot()
 profiles  = build_rig_profiles_from_snapshot(snapshot)
 ```
 
-**Body measurement accuracy improvements** in `docs/examples/body_measurements.py`:
+**Body measurement accuracy improvements** in [`geometry/body_measurements`](https://github.com/bluemoonfoundry/daz-script-server-examples/tree/main/geometry/body_measurements):
 
 - Slices now use centroid-weighted torso loop selection to filter arm cross-sections, correcting a ~70 cm overestimate on A-pose figures.
 - The heuristic fallback for unlabelled figures (e.g. a character named
@@ -550,11 +695,14 @@ print(anim.frame_range())          # (start, end)
 anim.bake_pose_to_keyframes(start=0, end=60)
 ```
 
-### 📐 math3 — Vec3, Quat, BoundingBox
+### 📐 math3 — Vec3, Quat, BoundingBox, AxisRemap
 
 New module **`dazpy.math3`** provides lightweight value types returned throughout
 the SDK: `Vec3` (positions, translations), `Quat` (rotations), and `BoundingBox`
 (geometry bounds).  All support arithmetic operators and round-trip through JSON.
+`AxisRemap` converts `Vec3`/`Quat`/`BoundingBox` values between axis conventions
+via signed-axis permutations (e.g. the built-in `Y_UP_TO_Z_UP` preset for
+converting DAZ Studio's Y-up scene data to Z-up tools like Blender).
 
 ### 🌐 Posed Vertex Export & USD Scene Export
 
@@ -562,7 +710,7 @@ the SDK: `Vec3` (positions, translations), `Quat` (rotations), and `BoundingBox`
 positions with skinning and morphs already applied — enabling downstream export
 pipelines to read the final mesh without re-solving the rig.
 
-New example **`docs/examples/scene_to_usd.py`** uses this to export a full live
+New example **[`export/scene_to_usd`](https://github.com/bluemoonfoundry/daz-script-server-examples/tree/main/export/scene_to_usd)** uses this to export a full live
 DAZ Studio scene to Pixar USD: posed meshes, cameras, lights, PBR materials, and
 strand-based hair as `UsdGeom.BasisCurves`.  Pass `--morphs` to write blend
 shapes as `UsdSkel` targets.
@@ -600,8 +748,8 @@ Studio instance) now ship in the repo root.
 
 ### 📖 Docs & Ergonomics
 
-- API reference pages for `DazPose`, `DazAnimation`, `Vec3`, `Quat`, and `BoundingBox`
-- Every script in `docs/examples/` has an `if __name__ == "__main__":` guard and
+- API reference pages for `DazPose`, `DazAnimation`, `Vec3`, `Quat`, `BoundingBox`, and `AxisRemap`
+- Every script in [daz-script-server-examples](https://github.com/bluemoonfoundry/daz-script-server-examples) has an `if __name__ == "__main__":` guard and
   argparse `--help`, making all examples safe to import and self-documenting
 
 ---
@@ -654,7 +802,7 @@ See the [full migration guide](MIGRATION.md) for upgrade steps and rollback inst
 
 Long-running operations (renders, exports, batch jobs) no longer need to block the HTTP connection:
 
-- **`POST /execute/async`** — Submit any inline script asynchronously; returns a `request_id` immediately
+- **`POST /execute/async`** — Submit inline `script` or host-side `scriptFile` work asynchronously; returns a `request_id` immediately
 - **`POST /scripts/:id/async`** — Submit a registered script asynchronously
 - **`GET /requests/:id/status`** — Poll for progress (`queued`, `running`, `completed`, `failed`, `cancelled`)
 - **`GET /requests/:id/result`** — Fetch the final result; supports `?wait=true` to long-poll until complete
@@ -665,6 +813,8 @@ Long-running operations (renders, exports, batch jobs) no longer need to block t
 
 **TTL:** Completed, failed, and cancelled requests are automatically purged after 1 hour (cleanup timer fires every 5 minutes).
 
+**Stale running requests:** If a request has been `running` for more than 30 minutes without completing — e.g. a render blocked behind a DAZ Studio modal dialog — it's automatically marked `failed` so polling clients aren't left waiting forever. The underlying DAZ Studio operation may still be stuck; check the DAZ Studio window directly if this happens.
+
 ---
 
 ## What's New in v1.2.0
@@ -712,7 +862,7 @@ automation code without authoring DazScript by hand.
 Download the `.whl` file from the [latest release](https://github.com/bluemoonfoundry/daz-script-server/releases/latest) and install it:
 
 ```bash
-pip install dazpy-2.8.0-py3-none-any.whl
+pip install dazpy-2.9.0-py3-none-any.whl
 ```
 
 Or install directly from the repo for development:
@@ -1636,10 +1786,36 @@ result = requests.get(f"{BASE}/requests/{req_id}/result?wait=true&timeout=300",
 
 ### `POST /execute/async`
 
-**Purpose:** Submit an inline script for asynchronous execution
+**Purpose:** Submit an inline script or host-side script file for asynchronous execution
 **Authentication:** Required (if enabled)
 
-**Request Body:** Same as `POST /execute`
+**Request Body:** Same as `POST /execute`, plus optional `reportFile` for
+structured job observation.
+
+`reportFile` is an absolute host-side path to a JSONL file owned by this job.
+The server truncates it when the request is accepted. The script may then write
+one JSON object per line. The path is injected into the script's argument object
+as reserved field `getArguments()[0].__dssReportFile`, so callers do not have to
+duplicate it inside `args`:
+
+```jsonl
+{"type":"progress","value":0.25,"current":1,"total":4,"phase":"render","message":"Plate 1"}
+{"type":"log","level":"info","message":"Loaded scene"}
+{"type":"output","path":"C:/renders/run/plate-1.png","kind":"image","label":"plate"}
+```
+
+Progress events require either `value` (0–1) or `current` plus `total`. Log
+events require `message`. Output events require `path`; repeating a path updates
+that manifest entry. A `manifest` event may provide an `outputs` array. Use a
+unique report file for every job.
+`reportFile` may not be the submitted `scriptFile`, because the server owns and
+truncates the former before the job is queued.
+
+DAZ Studio 6 ingests report events from polling workers, so progress, logs, and
+outputs are visible while the main thread is occupied by the script. DAZ Studio
+4's JSON parser is main-thread-only; Studio 4 therefore ingests the final report
+after execution returns and does not expose report-driven progress while the job
+is still running.
 
 **Response (immediate):**
 ```json
@@ -1673,7 +1849,15 @@ result = requests.get(f"{BASE}/requests/{req_id}/result?wait=true&timeout=300",
 {
   "request_id": "a3f2b891",
   "status": "running",
-  "progress": 0.0,
+  "progress": 0.25,
+  "observation": {
+    "progress": {"value": 0.25, "current": 1, "total": 4, "phase": "render"},
+    "log_tail": [{"level": "info", "source": "script", "message": "Loaded scene"}],
+    "log_total": 1,
+    "log_truncated": false,
+    "output_manifest": {"count": 0, "outputs": []},
+    "report_file": "C:/renders/run/job.jsonl"
+  },
   "elapsed_ms": 1240,
   "queue_position": 0
 }
@@ -1711,6 +1895,11 @@ result = requests.get(f"{BASE}/requests/{req_id}/result?wait=true&timeout=300",
 }
 ```
 
+Completed, failed, and cancelled results also include `observation`. The log
+tail is capped at the newest 100 entries; `log_total` and `log_truncated` make
+the loss explicit. Ordinary captured `print()` output is folded into the same
+tail at completion while remaining available in the legacy `output` field.
+
 Returns HTTP 404 if the request ID is unknown or has been purged (TTL: 1 hour).
 
 ---

dazpy-2.8.0/PKG-INFO → dazpy-2.9.3/README.md

@@ -1,21 +1,6 @@
-Metadata-Version: 2.4
-Name: dazpy
-Version: 2.8.0
-Summary: Python SDK for the DAZ Studio Script Server
-License: MIT
-Project-URL: Homepage, https://github.com/bluemoonfoundry/daz-script-server
-Project-URL: Repository, https://github.com/bluemoonfoundry/daz-script-server
-Project-URL: Bug Tracker, https://github.com/bluemoonfoundry/daz-script-server/issues
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.28
-Provides-Extra: docs
-Requires-Dist: sphinx>=7.0; extra == "docs"
-Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
-
 # DazScript Server
 
-**Version 2.8.0** | DAZ Studio 4.5+ | DAZ Studio 6.25+ | Windows & macOS
+**Version 2.9.3** | DAZ Studio 4.5+ | DAZ Studio 6.25+ | Windows & macOS
 
 [![Docs](https://img.shields.io/badge/docs-dazpy%20SDK-blue)](https://bluemoonfoundry.github.io/daz-script-server/)
 [![HTTP API](https://img.shields.io/badge/docs-HTTP%20API%20reference-blue)](https://bluemoonfoundry.github.io/daz-script-server/api-reference/)
@@ -78,11 +63,26 @@ print(response.json())
 
 ---
 
+## Examples
+
+**Complete example collection:** [daz-script-server-examples repository](https://github.com/bluemoonfoundry/daz-script-server-examples)
+
+Production-ready examples ranging from beginner tutorials to advanced pipeline implementations:
+- **48 examples** across 9 categories
+- Individual READMEs with skill level classification
+- Requirements.txt per example
+- Comprehensive searchable table
+
+Categories: fundamentals, character, animation, rendering, geometry, export, ml_data, ai_vision, bvh
+
+---
+
 ## 📋 Table of Contents
 
 ### Getting Started
 - [Quick Start](#-quick-start)
 - [Why This Exists](#why-this-exists)
+- [What's New in v2.9.0](#whats-new-in-v290)
 - [What's New in v2.8.0](#whats-new-in-v280)
 - [What's New in v2.7.2](#whats-new-in-v272)
 - [What's New in v2.7.1](#whats-new-in-v271)
@@ -170,6 +170,134 @@ DAZ Studio is powerful for 3D content creation, but automation is limited to man
 
 ---
 
+## What's New in v2.9.0
+
+### 🎬 dazpy.cinematics — camera shot builders
+
+`dazpy.cinematics` packages common camera choreography on top of
+`DazCamera`/`DazScene`: `apply_static_shot()` places/aims/configures a
+camera in one call; `apply_orbit_camera()` sweeps a camera around a target
+across a frame range; `apply_frame_subject()` frames a subject at a named
+shot distance (`close_up` / `medium` / `full_body`); and
+`apply_animated_shot()` writes real, interpolated DAZ Studio keyframes at a
+sequence of waypoints instead of baking a value on every frame.
+
+```python
+from dazpy.cinematics import OrbitCamera, apply_orbit_camera
+
+apply_orbit_camera(scene, OrbitCamera(target=figure, radius=250, frame_start=0, frame_end=90))
+```
+
+### 💡 dazpy.lighting — three-point rigs and HDRI environments
+
+`apply_three_point_light_setup()` creates and places a key/fill/rim light
+rig around a target in one call, via angle/distance placement or explicit
+world-space positions per light. `apply_hdri_environment()` applies
+image-based dome lighting — map, intensity, rotation, dome/scene mode,
+visibility, and IBL resolution — validating the image path up front and
+verifying a post-apply readback so a silent failure never passes as success.
+
+### 🧍 dazpy.poses — apply_pose, reset_transforms, zero_figure
+
+Common pose operations without hand-assembling a `DazPose`:
+`apply_pose()` applies a pose object or a JSON file path directly to a
+skeleton; `reset_transforms()` zeroes a node's local position/rotation and
+resets scale to 1.0; `zero_figure()` drives every bone rotation and morph
+to zero while leaving the figure's root transform untouched by default.
+
+### 📐 dazpy.math3.AxisRemap — coordinate-space conversion
+
+A generic signed-axis-permutation converter for `Vec3`/`Quat`/
+`BoundingBox` between coordinate conventions, with a ready-made
+`Y_UP_TO_Z_UP` preset for moving data from DAZ Studio (Y-up) into
+Blender/glTF-style Z-up pipelines.
+
+```python
+from dazpy.math3 import Y_UP_TO_Z_UP
+
+blender_pos = Y_UP_TO_Z_UP.apply_vec3(daz_pos)
+```
+
+### 🦴 DazSkeleton.bone_rotations_quat()
+
+Returns local-space quaternion rotations for every bone in one HTTP
+round-trip — the composable counterpart to `bone_rotations()` for callers
+feeding the result into another rotation (e.g. `AxisRemap.apply_quat()`),
+sidestepping the per-bone Euler rotation-order tracking that would
+otherwise be required.
+
+### 🎞️ Frame-level progress streaming for animation renders
+
+The `GET /render/:id/progress` SSE stream now emits a progress event at
+each frame boundary during an animation render, instead of only start/
+terminal events — the DAZ SDK exposes no per-percent render progress
+signal, so this frame-level marker is the most granular progress available.
+
+### ⚡ Async client — `dazpy.aio.AsyncDazClient`
+
+Async frameworks (FastAPI, FastMCP, ComfyUI custom nodes, asyncio/Temporal
+workflows) previously had to wrap every `DazClient` call in
+`asyncio.to_thread()` or hand-roll an `httpx.AsyncClient` wrapper.
+`dazpy.aio.AsyncDazClient` mirrors `DazClient`'s full method surface —
+`execute`, `execute_file`, inline/file async submit/status/result/list/cancel, render
+submit/batch/animation, USD export, and server-health endpoints — as
+native `async def` methods backed by `httpx.AsyncClient`, including the
+same `retry_on_busy`/`max_wait` backoff semantics (via `asyncio.sleep`
+instead of blocking `time.sleep`).
+
+```python
+from dazpy.aio import AsyncDazClient
+
+async def main():
+    async with AsyncDazClient() as client:
+        request_id = await client.execute_file_async_submit("C:/jobs/pose-probe.dsa")
+        result = await client.get_request_result(request_id, wait=True)
+        print(result)
+```
+
+Requires the optional `httpx` dependency: `pip install dazpy[aio]`.
+
+### `DazClient` connection pooling + `close()`
+
+`DazClient` now issues requests through a pooled `requests.Session` instead
+of a fresh connection per call, and supports `close()` / use as a context
+manager (`with DazClient() as client:`) for symmetry with the new async
+client's connection lifecycle.
+
+### Truthful Iray/Viewport render-engine selector
+
+`DazRenderSettings.render_engine_state()` now reads the effective
+`DzRenderOptions.renderType` value and the active renderer class/name as separate
+facts. Its schema-1 record includes the raw enum value/name, normalized
+`verified_iray` / `verified_non_iray` / `unavailable` status, and field-level
+live-readback provenance. A retained `NVIDIA Iray` active-renderer name never
+overrides a Viewport/OpenGL `renderType`.
+
+`DazRenderSettings.set_render_engine("iray" | "viewport")` is an explicit
+persistent setter. It selects the registered `DzIrayRenderer` plus `Software` for
+Iray, or `ScreenShot` for Viewport, calls `applyChanges()`, and returns only after
+exact readback. Missing renderers, mutation/apply faults, malformed replies, and
+readback disagreement raise `RenderError`; unknown engine names raise `ValueError`
+before dispatch.
+
+```python
+settings = DazRenderSettings(client)
+before = settings.render_engine_state()
+change = settings.set_render_engine("iray")
+assert change["readback"]["status"] == "verified_iray"
+```
+
+The `engine` field on `/render`, `/render/batch`, and `/render/animation` also
+accepts `viewport` and uses the same fail-closed mutation/readback rules. These
+operations intentionally persist the requested engine. DAZ documents `ScreenShot`
+and `HardwareAssisted` as Viewport/OpenGL operations and `Software` as the active
+software-renderer operation in the
+[DzRenderOptions reference](https://docs.daz3d.com/public/software/dazstudio/4/referenceguide/scripting/api_reference/object_index/renderoptions_dz);
+renderer lookup and activation are documented by
+[DzRenderMgr](https://docs.daz3d.com/public/software/dazstudio/4/referenceguide/scripting/api_reference/object_index/rendermgr_dz).
+
+---
+
 ## What's New in v2.8.0
 
 ### 🚦 Fail Fast When DAZ Studio Is Busy — `503 STUDIO_BUSY`
@@ -318,7 +446,7 @@ change.  For dirty scenes it serialises via `Scene.saveScene()` and restores
 the original filename immediately.  The `method` field in the response tells
 you which strategy was used.
 
-See `docs/examples/fundamentals/scene_save_copy.py` for a complete example
+See [`fundamentals/scene_save_copy`](https://github.com/bluemoonfoundry/daz-script-server-examples/tree/main/fundamentals/scene_save_copy) in the examples repo for a complete example
 with `--compare` and `--dry-run` options.
 
 ---
@@ -370,7 +498,7 @@ snapshot  = scene.scene_snapshot()
 profiles  = build_rig_profiles_from_snapshot(snapshot)
 ```
 
-**Body measurement accuracy improvements** in `docs/examples/body_measurements.py`:
+**Body measurement accuracy improvements** in [`geometry/body_measurements`](https://github.com/bluemoonfoundry/daz-script-server-examples/tree/main/geometry/body_measurements):
 
 - Slices now use centroid-weighted torso loop selection to filter arm cross-sections, correcting a ~70 cm overestimate on A-pose figures.
 - The heuristic fallback for unlabelled figures (e.g. a character named
@@ -550,11 +678,14 @@ print(anim.frame_range())          # (start, end)
 anim.bake_pose_to_keyframes(start=0, end=60)
 ```
 
-### 📐 math3 — Vec3, Quat, BoundingBox
+### 📐 math3 — Vec3, Quat, BoundingBox, AxisRemap
 
 New module **`dazpy.math3`** provides lightweight value types returned throughout
 the SDK: `Vec3` (positions, translations), `Quat` (rotations), and `BoundingBox`
 (geometry bounds).  All support arithmetic operators and round-trip through JSON.
+`AxisRemap` converts `Vec3`/`Quat`/`BoundingBox` values between axis conventions
+via signed-axis permutations (e.g. the built-in `Y_UP_TO_Z_UP` preset for
+converting DAZ Studio's Y-up scene data to Z-up tools like Blender).
 
 ### 🌐 Posed Vertex Export & USD Scene Export
 
@@ -562,7 +693,7 @@ the SDK: `Vec3` (positions, translations), `Quat` (rotations), and `BoundingBox`
 positions with skinning and morphs already applied — enabling downstream export
 pipelines to read the final mesh without re-solving the rig.
 
-New example **`docs/examples/scene_to_usd.py`** uses this to export a full live
+New example **[`export/scene_to_usd`](https://github.com/bluemoonfoundry/daz-script-server-examples/tree/main/export/scene_to_usd)** uses this to export a full live
 DAZ Studio scene to Pixar USD: posed meshes, cameras, lights, PBR materials, and
 strand-based hair as `UsdGeom.BasisCurves`.  Pass `--morphs` to write blend
 shapes as `UsdSkel` targets.
@@ -600,8 +731,8 @@ Studio instance) now ship in the repo root.
 
 ### 📖 Docs & Ergonomics
 
-- API reference pages for `DazPose`, `DazAnimation`, `Vec3`, `Quat`, and `BoundingBox`
-- Every script in `docs/examples/` has an `if __name__ == "__main__":` guard and
+- API reference pages for `DazPose`, `DazAnimation`, `Vec3`, `Quat`, `BoundingBox`, and `AxisRemap`
+- Every script in [daz-script-server-examples](https://github.com/bluemoonfoundry/daz-script-server-examples) has an `if __name__ == "__main__":` guard and
   argparse `--help`, making all examples safe to import and self-documenting
 
 ---
@@ -654,7 +785,7 @@ See the [full migration guide](MIGRATION.md) for upgrade steps and rollback inst
 
 Long-running operations (renders, exports, batch jobs) no longer need to block the HTTP connection:
 
-- **`POST /execute/async`** — Submit any inline script asynchronously; returns a `request_id` immediately
+- **`POST /execute/async`** — Submit inline `script` or host-side `scriptFile` work asynchronously; returns a `request_id` immediately
 - **`POST /scripts/:id/async`** — Submit a registered script asynchronously
 - **`GET /requests/:id/status`** — Poll for progress (`queued`, `running`, `completed`, `failed`, `cancelled`)
 - **`GET /requests/:id/result`** — Fetch the final result; supports `?wait=true` to long-poll until complete
@@ -665,6 +796,8 @@ Long-running operations (renders, exports, batch jobs) no longer need to block t
 
 **TTL:** Completed, failed, and cancelled requests are automatically purged after 1 hour (cleanup timer fires every 5 minutes).
 
+**Stale running requests:** If a request has been `running` for more than 30 minutes without completing — e.g. a render blocked behind a DAZ Studio modal dialog — it's automatically marked `failed` so polling clients aren't left waiting forever. The underlying DAZ Studio operation may still be stuck; check the DAZ Studio window directly if this happens.
+
 ---
 
 ## What's New in v1.2.0
@@ -712,7 +845,7 @@ automation code without authoring DazScript by hand.
 Download the `.whl` file from the [latest release](https://github.com/bluemoonfoundry/daz-script-server/releases/latest) and install it:
 
 ```bash
-pip install dazpy-2.8.0-py3-none-any.whl
+pip install dazpy-2.9.0-py3-none-any.whl
 ```
 
 Or install directly from the repo for development:
@@ -1636,10 +1769,36 @@ result = requests.get(f"{BASE}/requests/{req_id}/result?wait=true&timeout=300",
 
 ### `POST /execute/async`
 
-**Purpose:** Submit an inline script for asynchronous execution
+**Purpose:** Submit an inline script or host-side script file for asynchronous execution
 **Authentication:** Required (if enabled)
 
-**Request Body:** Same as `POST /execute`
+**Request Body:** Same as `POST /execute`, plus optional `reportFile` for
+structured job observation.
+
+`reportFile` is an absolute host-side path to a JSONL file owned by this job.
+The server truncates it when the request is accepted. The script may then write
+one JSON object per line. The path is injected into the script's argument object
+as reserved field `getArguments()[0].__dssReportFile`, so callers do not have to
+duplicate it inside `args`:
+
+```jsonl
+{"type":"progress","value":0.25,"current":1,"total":4,"phase":"render","message":"Plate 1"}
+{"type":"log","level":"info","message":"Loaded scene"}
+{"type":"output","path":"C:/renders/run/plate-1.png","kind":"image","label":"plate"}
+```
+
+Progress events require either `value` (0–1) or `current` plus `total`. Log
+events require `message`. Output events require `path`; repeating a path updates
+that manifest entry. A `manifest` event may provide an `outputs` array. Use a
+unique report file for every job.
+`reportFile` may not be the submitted `scriptFile`, because the server owns and
+truncates the former before the job is queued.
+
+DAZ Studio 6 ingests report events from polling workers, so progress, logs, and
+outputs are visible while the main thread is occupied by the script. DAZ Studio
+4's JSON parser is main-thread-only; Studio 4 therefore ingests the final report
+after execution returns and does not expose report-driven progress while the job
+is still running.
 
 **Response (immediate):**
 ```json
@@ -1673,7 +1832,15 @@ result = requests.get(f"{BASE}/requests/{req_id}/result?wait=true&timeout=300",
 {
   "request_id": "a3f2b891",
   "status": "running",
-  "progress": 0.0,
+  "progress": 0.25,
+  "observation": {
+    "progress": {"value": 0.25, "current": 1, "total": 4, "phase": "render"},
+    "log_tail": [{"level": "info", "source": "script", "message": "Loaded scene"}],
+    "log_total": 1,
+    "log_truncated": false,
+    "output_manifest": {"count": 0, "outputs": []},
+    "report_file": "C:/renders/run/job.jsonl"
+  },
   "elapsed_ms": 1240,
   "queue_position": 0
 }
@@ -1711,6 +1878,11 @@ result = requests.get(f"{BASE}/requests/{req_id}/result?wait=true&timeout=300",
 }
 ```
 
+Completed, failed, and cancelled results also include `observation`. The log
+tail is capped at the newest 100 entries; `log_total` and `log_truncated` make
+the loss explicit. Ordinary captured `print()` output is folded into the same
+tail at completion while remaining available in the legacy `output` field.
+
 Returns HTTP 404 if the request ID is unknown or has been purged (TTL: 1 hour).
 
 ---