@bluemoonfoundry/daz-ts 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +377 -2
  3. package/dist/animation.d.ts +129 -0
  4. package/dist/animation.js +276 -0
  5. package/dist/batch.d.ts +118 -0
  6. package/dist/batch.js +186 -0
  7. package/dist/bone.d.ts +50 -0
  8. package/dist/bone.js +66 -0
  9. package/dist/camera.d.ts +61 -0
  10. package/dist/camera.js +120 -0
  11. package/dist/cinematics.d.ts +188 -0
  12. package/dist/cinematics.js +165 -0
  13. package/dist/client.d.ts +399 -0
  14. package/dist/client.js +769 -0
  15. package/dist/dforce.d.ts +15 -0
  16. package/dist/dforce.js +36 -0
  17. package/dist/element.d.ts +51 -0
  18. package/dist/element.js +141 -0
  19. package/dist/exceptions.d.ts +124 -0
  20. package/dist/exceptions.js +173 -0
  21. package/dist/geometry.d.ts +81 -0
  22. package/dist/geometry.js +433 -0
  23. package/dist/index.d.ts +50 -0
  24. package/dist/index.js +36 -0
  25. package/dist/light.d.ts +24 -0
  26. package/dist/light.js +40 -0
  27. package/dist/lighting.d.ts +120 -0
  28. package/dist/lighting.js +107 -0
  29. package/dist/material.d.ts +27 -0
  30. package/dist/material.js +63 -0
  31. package/dist/materials.d.ts +107 -0
  32. package/dist/materials.js +165 -0
  33. package/dist/math3.d.ts +204 -0
  34. package/dist/math3.js +502 -0
  35. package/dist/modifier.d.ts +14 -0
  36. package/dist/modifier.js +24 -0
  37. package/dist/morph.d.ts +11 -0
  38. package/dist/morph.js +24 -0
  39. package/dist/node.d.ts +196 -0
  40. package/dist/node.js +447 -0
  41. package/dist/polling.d.ts +24 -0
  42. package/dist/polling.js +50 -0
  43. package/dist/pose.d.ts +82 -0
  44. package/dist/pose.js +295 -0
  45. package/dist/poses.d.ts +54 -0
  46. package/dist/poses.js +40 -0
  47. package/dist/property.d.ts +64 -0
  48. package/dist/property.js +125 -0
  49. package/dist/render.d.ts +242 -0
  50. package/dist/render.js +811 -0
  51. package/dist/renderApi.d.ts +124 -0
  52. package/dist/renderApi.js +235 -0
  53. package/dist/result.d.ts +15 -0
  54. package/dist/result.js +1 -0
  55. package/dist/scene.d.ts +154 -0
  56. package/dist/scene.js +584 -0
  57. package/dist/sceneEvents.d.ts +63 -0
  58. package/dist/sceneEvents.js +102 -0
  59. package/dist/sceneState.d.ts +167 -0
  60. package/dist/sceneState.js +430 -0
  61. package/dist/scriptBuilder.d.ts +41 -0
  62. package/dist/scriptBuilder.js +72 -0
  63. package/dist/shotGeometry.d.ts +49 -0
  64. package/dist/shotGeometry.js +76 -0
  65. package/dist/skeleton.d.ts +120 -0
  66. package/dist/skeleton.js +561 -0
  67. package/dist/timeline.d.ts +24 -0
  68. package/dist/timeline.js +39 -0
  69. package/dist/undo.d.ts +24 -0
  70. package/dist/undo.js +45 -0
  71. package/dist/version.d.ts +31 -0
  72. package/dist/version.js +36 -0
  73. package/dist/viewport.d.ts +58 -0
  74. package/dist/viewport.js +239 -0
  75. package/package.json +52 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 DazScriptServer contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,378 @@
1
- # Temporary Holding Version
1
+ # daz-ts
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ TypeScript SDK for [DazScriptServer](../README.md), the HTTP server plugin
4
+ that embeds an HTTP API inside DAZ Studio for remotely executing DazScript
5
+ code. `daz-ts` is the Node.js/TypeScript counterpart to
6
+ [`dazpy`](../dazpy), the mature Python SDK — same wire protocol, same
7
+ server, a single `DazClient` class (no sync/async split; `async`/`await`
8
+ covers both). Phase 1 shipped the client core (`execute`, async job
9
+ submission/polling, batching, render submission, SSE plumbing) plus a
10
+ dependency-free `math3` module. Phase 2 (below) adds the scene-graph proxy
11
+ layer (nodes, materials, skeletons, etc.).
12
+
13
+ ## Install
14
+
15
+ ```bash
16
+ npm install @bluemoonfoundry/daz-ts
17
+ ```
18
+
19
+ For offline installs, each `daz-ts-v*` [GitHub release](https://github.com/bluemoonfoundry/daz-script-server/releases)
20
+ also carries the `bluemoonfoundry-daz-ts-*.tgz` tarball:
21
+
22
+ ```bash
23
+ npm install ./bluemoonfoundry-daz-ts-0.1.0.tgz
24
+ ```
25
+
26
+ Requires Node.js >= 18 (for built-in `fetch`/`AbortController`).
27
+
28
+ ## Auth
29
+
30
+ Same convention as `dazpy`: requests carry an `X-API-Token` header. By
31
+ default, `DazClient` auto-loads the token from
32
+ `~/.daz3d/dazscriptserver_token.txt` (the file DazScriptServer writes on
33
+ first run). You can also pass a token explicitly, or pass `token: ""` to
34
+ disable authentication (only if the server has auth disabled too):
35
+
36
+ ```ts
37
+ import { DazClient } from "@bluemoonfoundry/daz-ts";
38
+
39
+ const client = new DazClient(); // auto-loads token from ~/.daz3d/...
40
+ const explicit = new DazClient({ token: "your-token-here" });
41
+ const noAuth = new DazClient({ token: "" });
42
+ ```
43
+
44
+ `DazClientOptions` also accepts `host` (default `"127.0.0.1"`), `port`
45
+ (default `18811`), and `timeoutMs` (default `30000`).
46
+
47
+ ## Usage
48
+
49
+ ### `DazClient.execute()`
50
+
51
+ Run a DazScript string synchronously and get back its result, captured
52
+ console output, and timing:
53
+
54
+ ```ts
55
+ import { DazClient } from "@bluemoonfoundry/daz-ts";
56
+
57
+ const client = new DazClient();
58
+
59
+ const result = await client.execute("2 + 2;");
60
+ console.log(result.value); // 4
61
+ console.log(result.output); // string[] of captured log lines
62
+ console.log(result.durationMs);
63
+ ```
64
+
65
+ Pass a JSON-serializable `args` value as the script's `getArguments()[0]`:
66
+
67
+ ```ts
68
+ await client.execute("var n = getArguments()[0].count; n * 2;", { count: 21 });
69
+ ```
70
+
71
+ Script errors and busy/authentication failures throw typed exceptions
72
+ (`ScriptSyntaxError`, `ScriptRuntimeError`, `StudioBusyError`,
73
+ `ConcurrencyLimitError`, `AuthenticationError`, `ConnectionError`,
74
+ `DazTimeoutError`, ...) — see `src/exceptions.ts` for the full hierarchy.
75
+ Any method that accepts a trailing `{ retryOnBusy, maxWait }` option
76
+ (`RetryOptions`) will transparently retry with linear backoff on
77
+ `StudioBusyError`/`ConcurrencyLimitError` instead of throwing immediately:
78
+
79
+ ```ts
80
+ await client.execute("doSomethingSlow();", undefined, { retryOnBusy: true, maxWait: 30 });
81
+ ```
82
+
83
+ ### `Batch`
84
+
85
+ Collect multiple operations and run them as a single HTTP round-trip
86
+ (one script, one `/execute` call). Execution is **serial**, with **no
87
+ parallelism** and **no transactionality** — a failing operation fails the
88
+ whole call, and earlier mutations already applied to the live scene are
89
+ **not** rolled back:
90
+
91
+ ```ts
92
+ import { Batch, DazClient } from "@bluemoonfoundry/daz-ts";
93
+
94
+ const client = new DazClient();
95
+ const batch = new Batch(client); // options: { maxOperations, maxScriptLength }
96
+
97
+ const nameFuture = batch.addOperation(["var n = Scene.findNode('Genesis9');"], "n.getLabel()");
98
+ const posFuture = batch.addOperation(
99
+ ["var n = Scene.findNode('Genesis9');", "var p = n.getWSPos();"],
100
+ "[p.x, p.y, p.z]",
101
+ );
102
+
103
+ await batch.execute(); // one HTTP call resolves every future
104
+
105
+ console.log(nameFuture.value, posFuture.value);
106
+ ```
107
+
108
+ `addPrelude(preludeKey, lines)` registers a shared setup block emitted once
109
+ per unique key, useful when several operations depend on the same lookup.
110
+ `DazClient.executeBatchAsync(operations, args?)` submits the same
111
+ single-script batch shape to the async endpoint (`/execute/async`) for
112
+ long-running batches — poll it like any other async request.
113
+
114
+ ### `executeLong()`
115
+
116
+ Run a potentially long-running script via the async endpoint, with polling
117
+ handled for you:
118
+
119
+ ```ts
120
+ import { executeLong } from "@bluemoonfoundry/daz-ts";
121
+
122
+ const result = await executeLong(client, "renderEverything();", undefined, {
123
+ timeoutMs: 300_000, // default 120000
124
+ pollIntervalMs: 500, // default 500
125
+ });
126
+ ```
127
+
128
+ It submits the script with `executeAsyncSubmit`, then long-polls
129
+ `/requests/:id/result` until the script completes, fails, is cancelled, or
130
+ `timeoutMs` elapses (throwing `AsyncExecutionError` or `DazTimeoutError`
131
+ respectively).
132
+
133
+ A running script can't be interrupted, so cancelling it only moves it to
134
+ `cancel_requested`; `executeLong` keeps waiting, and resolves with the result
135
+ if the job ends `completed_after_cancel_request`. A job running past the
136
+ server's Stuck Job Timeout becomes `stale`, which ends the wait with
137
+ `AsyncExecutionError` (the script may still finish later, as
138
+ `completed_after_stale`). The `RequestStatus` type and
139
+ `FINAL_REQUEST_STATUSES` list every status, and
140
+ `client.cancelRequestDetail(id)` returns the server's cancel response
141
+ (`status` is `cancelled`, `cancel_requested` or `stale`).
142
+
143
+ ### `DazClient.checkServerVersion()`
144
+
145
+ daz-ts needs DazScriptServer plugin 2.11 or newer (`MIN_SERVER_VERSION`).
146
+ Unlike dazpy, it never checks the plugin version on its own. Call
147
+ `checkServerVersion()` once after connecting if you want to warn about an
148
+ old plugin:
149
+
150
+ ```ts
151
+ const check = await client.checkServerVersion(); // GET /status
152
+ if (check.compatible === false) console.warn(check.message);
153
+ ```
154
+
155
+ `compatible` is `null` when the plugin reports no parseable version.
156
+ `evaluateServerVersion(url, statusBody)` and `parseVersion()` are exported
157
+ for callers that fetch `/status` themselves.
158
+
159
+ ### `DazClient.capabilities()`
160
+
161
+ Ask the server what it supports instead of hard-coding versions (requires a
162
+ DazScriptServer with `GET /capabilities`; older servers throw `DazError` on
163
+ 404):
164
+
165
+ ```ts
166
+ const caps = await client.capabilities();
167
+ if (caps.render_engines.selectable.includes("iray")) {
168
+ await client.renderSubmit("C:\\out.png", { engine: "iray" });
169
+ }
170
+ caps.limits.max_batch_variants; // current server limit
171
+ caps.compatibility_hash; // changes only when routes/features change
172
+ ```
173
+
174
+ `render_engines.source` is `"snapshot"` when Studio was busy and the server
175
+ answered from its last cached document.
176
+
177
+ ### Artifacts: downloading job outputs
178
+
179
+ Fetch the files a job declared without sharing DAZ Studio's filesystem
180
+ (requires a DazScriptServer with `GET /artifacts`). A job's artifacts are its
181
+ `reportFile` outputs plus the image(s) a render wrote:
182
+
183
+ ```ts
184
+ const sub = await client.renderSubmit("C:/renders/shot.png", { engine: "iray" });
185
+ const request_id = sub.request_id as string;
186
+ await client.getRequestResult(request_id, true, 600);
187
+
188
+ const list = await client.listArtifacts(request_id); // size, content_type, available
189
+ const png = await client.downloadArtifact(request_id, 0); // Buffer
190
+ await client.downloadArtifact(request_id, 0, "./shot.png"); // stream to file
191
+ const head = await client.downloadArtifact(request_id, 0, { range: [0, 1023] });
192
+ await client.downloadArtifacts(request_id, "./out"); // all available
193
+ ```
194
+
195
+ Rejections throw `ArtifactError` with `statusCode` and `errorCode`
196
+ (`ARTIFACT_NOT_FOUND` 404, `ARTIFACT_UNAVAILABLE` 410, `REQUEST_NOT_FOUND`
197
+ 404, or 416 for a range outside the file).
198
+
199
+ ## What else is here
200
+
201
+ - `math3.ts` — dependency-free `Vec3`, `Quat`, `BoundingBox`, `AxisRemap`
202
+ math utilities (no HTTP coupling).
203
+ - `ScriptBuilder` — the injection-safety helpers (`escapeString`, `iife`,
204
+ `serializeArg`) used internally to build generated DazScript source; every
205
+ injected string goes through `JSON.stringify`.
206
+ - Render submission methods (`renderSubmit`, `renderBatchSubmit`,
207
+ `renderAnimationSubmit`, ...) and SSE streaming helpers
208
+ (`streamRenderProgress`, `streamSceneEvents`, `parseSseStream`) on
209
+ `DazClient` — see `src/client.ts` for full signatures. The stream methods
210
+ take `{ timeoutMs, signal }`: `timeoutMs` caps the stream's whole lifetime
211
+ (reads throw `DazTimeoutError` when it elapses) and `signal` lets you
212
+ cancel it. They throw `ConnectionError`/`AuthenticationError` rather than
213
+ returning `null`; `null` means the server answered with another status
214
+ (e.g. 404).
215
+
216
+ The client's `timeoutMs` covers the whole request, including reading the
217
+ response body. Long-polls (`getRequestResult(id, true, waitTimeout)`) get
218
+ `waitTimeout` plus 10 seconds instead, and artifact downloads are streamed,
219
+ so only their time to first byte is bounded.
220
+
221
+ ## Phase 2: Scene Graph Proxies
222
+
223
+ Phase 2 adds a scene-graph proxy layer on top of the Phase 1 client core —
224
+ typed, promise-based wrappers around DAZ Studio's `DzNode`/`DzElement`
225
+ object model, ported from `dazpy`'s equivalent classes. Every property
226
+ getter/setter is an async method pair (`foo()`/`setFoo()`) rather than a TS
227
+ accessor, since accessors can't be `async`.
228
+
229
+ - `DazElement` — base proxy for any `DzElement`-derived object (locator
230
+ resolution and property get/set by label).
231
+ - `DazProperty` — a single node/material property (`value()`, `setValue()`,
232
+ keyframe helpers, and the `rawValue`/`setDoubleValue`/`getNumKeys` gotchas
233
+ ported from dazpy).
234
+ - `DazNode`, `NodeIdentifier` — the general scene-node proxy (transforms,
235
+ visibility, selection, parenting, `findProperty()`) and the `{value, kind}`
236
+ shape used to resolve nodes by name or label.
237
+ - `DazScene` — the primary entry point: node/camera/light/skeleton
238
+ factories, selection, bulk scene snapshots (`overview()`,
239
+ `sceneSnapshot()`, `allNodeTransforms()`, `nodeTree()`,
240
+ `nodeHierarchy()`), scene I/O (`load()`, `save()`, `exportFbx()`,
241
+ `exportObj()`), playback/frame range, dForce simulation, and
242
+ `undo()`/`UndoGroup` integration.
243
+ - `DazSkeleton` — figure proxy: bones, pose/morph values, bone-rotation
244
+ bake, IK-free pose evaluation.
245
+ - `DazBone` — a single skeleton bone (rotation, local/world position).
246
+ - `DazCamera` — camera-specific node proxy (focal length, FOV, DOF).
247
+ - `DazLight` — light-specific node proxy (intensity, color, shadow
248
+ settings).
249
+ - `DazMaterial` — a single surface's material properties.
250
+ - `DazModifier`, `DazMorph`, `DazDForce` — modifier-stack proxies: general
251
+ modifiers, ERC morphs, and dForce simulation modifiers.
252
+ - `DazGeometry` — a node's resolved mesh geometry (vertex positions,
253
+ bounding box, posed vs. unposed).
254
+ - `DazViewport` — the active 3D viewport (draw style, size, `capture()`).
255
+ - `DazTimeline` — the global timeline (current frame, frame range,
256
+ play/pause).
257
+ - `UndoGroup`, `withUndo` — group a series of changes into a single undo
258
+ step; `withUndo(client, label, fn)` is the TS equivalent of dazpy's
259
+ `with scene.undo(label): ...` context manager (TS has no `with`
260
+ statement).
261
+
262
+ `capture_sprite()` (dazpy's `rembg`-based background removal) and
263
+ IK-dependent methods (`DazSkeleton.handToTarget`/`.footToTarget`,
264
+ `DazScene.applyInteractionRecipe`) are out of scope for this phase — they
265
+ require the Phase 5 IK solver.
266
+
267
+ See `test/integration/proxies.integration.test.ts` for a live-server
268
+ integration suite covering these classes (gated on `DAZ_SERVER_URL`, same
269
+ pattern as Phase 1's `client.integration.test.ts`; run with
270
+ `DAZ_SERVER_URL=http://127.0.0.1:18811 npm run test:integration`).
271
+
272
+ See `docs/superpowers/specs/2026-09-06-daz-ts-design.md` (in the repo root)
273
+ for the full design spec and phased roadmap.
274
+
275
+ ## Phase 3: Rendering
276
+
277
+ Phase 3 adds live Render Settings control and high-level render helpers on
278
+ top of Phase 1's raw job-queue client methods, ported from `dazpy`'s
279
+ `_render.py` and `_render_api(_aio).py`.
280
+
281
+ - `DazRenderSettings` — talks directly to DAZ Studio's render manager
282
+ (`App.getRenderMgr()`) via `DazClient.execute()`: engine selection
283
+ (`activeEngine()`/`setActiveEngine()`, plus the stricter
284
+ `renderEngineState()`/`setRenderEngine()` pair that requires an exact live
285
+ readback before reporting success), resolution, output path, gamma,
286
+ double-sided rendering, Iray quality (`maxSamples`, `maxTimeSecs`,
287
+ `quality`, `setQualityPreset()`), Iray Canvases (`listCanvases()`,
288
+ `addCanvas()`, `removeCanvas()`, `canvasOutputPaths()`), and `render()` /
289
+ `renderAndWait()`, which drive `DzRenderMgr.doRender()` synchronously and
290
+ resolve from its `renderFinished(bool)` signal rather than trusting
291
+ `doRender()`'s own (undocumented, unreliable-on-cancel) return value.
292
+ - `Canvas`, `RenderOutcome` — plain result types for the above. Unlike
293
+ dazpy's `RenderOutcome` (which overrides `__bool__`), TS callers must
294
+ check `.success` explicitly.
295
+ - `render()`, `renderVariants()` (in `renderApi.ts`) — high-level helpers
296
+ over the HTTP `/render` and `/render/batch` job-queue endpoints already on
297
+ `DazClient` (`renderSubmit`, `renderBatchSubmit`, `streamRenderProgress`).
298
+ Both wait for completion via the SSE progress stream
299
+ (`GET /render/:id/progress`), falling back to long-poll on
300
+ `/requests/:id/result` if the stream is unavailable or ends without a
301
+ `complete`/`error` event. `renderVariants()` submits every variant in one
302
+ batch request, then awaits each in order, recording a failed variant's
303
+ error without aborting the rest.
304
+
305
+ `DazRenderSettings`'s environment-map/property methods
306
+ (`getEnvironmentProperty`, `setEnvironmentProperty`,
307
+ `setEnvironmentPropertyFromString`, `setEnvironmentMap`) are exposed
308
+ primarily for the Phase 4 `lighting.ts` domain helper, mirroring dazpy's
309
+ `lighting.py` usage of `_render.py`'s equivalent internal methods.
310
+
311
+ ## Phase 4: Capture/Restore and Domain Helpers
312
+
313
+ Phase 4 ports dazpy's checkpoint/restore primitives and its higher-level
314
+ domain-helper modules, which apply typed configuration objects to the Phase
315
+ 2/3 proxies rather than wrapping them in new classes ("typed data +
316
+ `apply()` function", matching dazpy's own module-function style for these).
317
+
318
+ - `DazPose` (`pose.ts`, from `_pose.py`) — a figure's complete pose
319
+ (sparse bone rotations, morphs, node properties), captured/applied via
320
+ each channel's *raw* (pre-ERC) value so repeated capture/apply cycles stay
321
+ idempotent even on `DzERCLink`-driven dials. `capture()`/`apply()`/
322
+ `applyFull()` are async (one HTTP call each); `lerp()`/`toDict()`/
323
+ `fromDict()`/`save()`/`load()` are pure/local.
324
+ - `DazSceneState` (`sceneState.ts`, from `_scene_state.py`) — a pose
325
+ checkpoint, not a full scene snapshot: every skeleton's `DazPose`, plus
326
+ camera/light transforms and a few extra light properties, restored in a
327
+ small fixed number of HTTP calls. Materials, render settings and deleted
328
+ nodes are not covered; `capture(scene, { backupPath })` first writes a
329
+ full-scene backup via `saveCopy()` for that. `apply()` returns a report:
330
+ `restored`, `skipped` (nodes deleted since capture, each also listed in
331
+ `errors`), `errors`, `complete` and `backup`. `apply()` independently verifies each skeleton restore with a
332
+ fresh `DazPose.capture()` read-back (retrying up to `maxVerifyRetries`
333
+ times on mismatch) since a 200 response can reflect a restore DAZ
334
+ Studio's main thread only partially executed under contention, and
335
+ restores each skeleton's conform/fit-to relationship via the real
336
+ `followTarget()`/`fitTo()`/`unfit()` API rather than trusting
337
+ `DazPose.applyFull()`'s generic property write-back.
338
+ - `DazAnimation` (`animation.ts`, from `_animation.py`) — a captured
339
+ timeline clip (parallel-list bone rotations + optional varying-morph
340
+ detection per frame). `capture()`/`apply()` are async; `clip()`/`blend()`/
341
+ `asPose()`/`append()` are pure.
342
+ - `shotGeometry.ts` (from `_shot_geometry.py`) — pure camera/light placement
343
+ math (`sphericalOffset`, `lookAtEuler`, `resolveTarget`) shared by
344
+ `lighting.ts` and `cinematics.ts`. `resolveTarget` is async in TS (unlike
345
+ Python's synchronous property access) since resolving a `DazNode` target
346
+ requires an HTTP round-trip via `position()`.
347
+ - `poses.ts` (from `poses.py`) — `applyPose`, `resetTransforms`,
348
+ `zeroFigure` convenience wrappers over `DazPose`/`DazNode`/`DazSkeleton`.
349
+ - `materials.ts` (from `materials.py`) — `IrayMaterial`/`TextureMap`/
350
+ `SurfaceProperty` typed specs plus `applyIrayMaterial`/`applyTextureMap`/
351
+ `getSurfaceProperty`/`setSurfaceProperty` over `DazMaterial`. Texture
352
+ paths are validated (absolute + exists on disk) before any DazScript call
353
+ is made, since an invalid path passed to the underlying `setMap()` can
354
+ hang or crash DAZ Studio via a blocking file-not-found dialog.
355
+ - `lighting.ts` (from `lighting.py`) — `applyThreePointLightSetup` (key/
356
+ fill/rim rig via `shotGeometry`) and `applyHdriEnvironment` (drives
357
+ `DazRenderSettings`'s environment-holder methods, verifying the apply via
358
+ an "Environment Intensity" readback).
359
+ - `cinematics.ts` (from `cinematics.py`) — `applyStaticShot`,
360
+ `applyOrbitCamera` (a per-frame sweep via `scene.setFrame()`, **not** real
361
+ keyframes — widens the scene's animation range as a documented side
362
+ effect), `applyFrameSubject` (shot-distance presets), and
363
+ `applyAnimatedShot` (real DAZ Studio keyframes via
364
+ `setPositionAtFrame`/`setRotationAtFrame`, letting DAZ Studio interpolate).
365
+ - `sceneEvents.ts` (from `_scene_events.py`) — `watchSceneEvents`/
366
+ `waitForSceneEvent`, typed SSE parsing over `GET /scene/events`, reusing
367
+ `client.ts`'s `parseSseStream`/`streamSceneEvents` already added in
368
+ Phase 3 for the render-progress stream.
369
+
370
+ Client-side input validation (file existence, path shape) happens in every
371
+ domain helper that touches user-supplied filesystem paths (`materials.ts`,
372
+ `lighting.ts`'s `applyHdriEnvironment`), matching dazpy's
373
+ blocking-dialog-avoidance pattern — a bad path reaching DAZ Studio's
374
+ underlying `setMap()`/environment-map call can hang or crash the app via a
375
+ modal file-not-found dialog rather than raising a script error.
376
+
377
+ Not ported in Phase 4: `_interaction.py` (multi-figure IK posing) — that's
378
+ Phase 5 (`daz-script-server-sf7y`).
@@ -0,0 +1,129 @@
1
+ /**
2
+ * A captured animation clip: bone rotations (and optionally morphs) for
3
+ * every frame in the play range. Mirrors dazpy's `_animation.py`.
4
+ */
5
+ import { DazPose } from "./pose.js";
6
+ import type { DazSkeleton } from "./skeleton.js";
7
+ /** One captured timeline frame. */
8
+ export interface AnimationFrame {
9
+ frame: number;
10
+ rotations: Array<[number, number, number]>;
11
+ morphs: Record<string, number>;
12
+ }
13
+ /** Plain-object schema matching {@link DazAnimation.toDict} and the animation JSON file format. */
14
+ export interface DazAnimationDict {
15
+ figure: string;
16
+ frame_range: {
17
+ start: number;
18
+ end: number;
19
+ };
20
+ bones: string[];
21
+ frames: AnimationFrame[];
22
+ }
23
+ /**
24
+ * A captured animation clip: bone rotations (and optionally morphs) for
25
+ * every frame in the play range.
26
+ *
27
+ * Created with {@link capture}; saved/loaded with {@link save}/{@link load}.
28
+ *
29
+ * Bones are stored as a parallel-list encoding -- a single ordered `bones`
30
+ * list of names, and per-frame `rotations` arrays aligned to that index --
31
+ * so payload size grows with bones x frames rather than with a full dict
32
+ * per frame.
33
+ *
34
+ * Typical workflow:
35
+ * ```ts
36
+ * const scene = new DazScene();
37
+ * const figure = await scene.findSkeletonByLabel("Genesis 9");
38
+ *
39
+ * const anim = await DazAnimation.capture(figure, true);
40
+ * anim.save("walk.json");
41
+ * ```
42
+ */
43
+ export declare class DazAnimation {
44
+ readonly figure: string;
45
+ readonly frameRange: {
46
+ start: number;
47
+ end: number;
48
+ };
49
+ readonly bones: string[];
50
+ readonly frames: AnimationFrame[];
51
+ constructor(figure: string, frameRange: {
52
+ start: number;
53
+ end: number;
54
+ }, bones: string[], frames: AnimationFrame[]);
55
+ /**
56
+ * Capture the full animation of `skeleton` in a single HTTP call.
57
+ *
58
+ * Scrubs every frame in the scene's play range server-side (no round-trip
59
+ * per frame). The timeline is restored to its original frame before the
60
+ * call returns.
61
+ *
62
+ * When `includeMorphs` is `true`, the script first identifies which
63
+ * geometry morphs and node-level properties actually vary across the
64
+ * timeline (channels that are keyed but static are excluded), then
65
+ * records their values per frame.
66
+ *
67
+ * @throws NodeNotFoundError If the skeleton is not found.
68
+ */
69
+ static capture(skeleton: DazSkeleton, includeMorphs?: boolean): Promise<DazAnimation>;
70
+ /** Load an animation from a JSON file. Accepts files produced by {@link save}. */
71
+ static load(path: string): DazAnimation;
72
+ /** Write this animation to a JSON file. Parent directories must exist. */
73
+ save(path: string): void;
74
+ /** Return the animation as a plain dict (same schema as the JSON file). */
75
+ toDict(): DazAnimationDict;
76
+ /**
77
+ * Return a new animation containing only frames in [start, end].
78
+ *
79
+ * `start` and `end` are scene frame numbers (the `frame` value stored in
80
+ * each frame, not array indices). Both endpoints are inclusive.
81
+ */
82
+ clip(start: number, end: number): DazAnimation;
83
+ /**
84
+ * Blend this animation with `other` frame by frame.
85
+ *
86
+ * Each frame's bone rotations and morph values are linearly interpolated
87
+ * between `this` (`t=0`) and `other` (`t=1`). Pure -- no HTTP round-trip.
88
+ *
89
+ * If the two clips have different frame counts, the result is truncated
90
+ * to the shorter clip. Frame numbers are taken from `this`.
91
+ *
92
+ * @throws Error If `this` and `other` have different bone lists.
93
+ */
94
+ blend(other: DazAnimation, t: number): DazAnimation;
95
+ /**
96
+ * Extract a single frame as a {@link DazPose}.
97
+ *
98
+ * Bone rotations are stored sparsely -- only bones with at least one
99
+ * non-zero component are included. Morph values are copied as-is. Pure --
100
+ * no HTTP round-trip.
101
+ *
102
+ * @param frameIndex 0-based index into {@link frames}.
103
+ */
104
+ asPose(frameIndex?: number): DazPose;
105
+ /**
106
+ * Apply a single frame of this animation to `skeleton`.
107
+ *
108
+ * Equivalent to `(await anim.asPose(frameIndex)).apply(skeleton)` -- one
109
+ * HTTP call that sets only the channels present in the frame.
110
+ *
111
+ * @param frameIndex 0-based index into {@link frames}. Defaults to 0.
112
+ */
113
+ apply(skeleton: DazSkeleton, frameIndex?: number): Promise<void>;
114
+ /**
115
+ * Concatenate `other` immediately after this animation.
116
+ *
117
+ * The other clip's frame numbers are shifted so it starts on the frame
118
+ * following this animation's last frame. The figure label and bone list
119
+ * are taken from `this`. Pure -- no HTTP round-trip.
120
+ *
121
+ * @throws Error If `this` and `other` have different bone lists.
122
+ */
123
+ append(other: DazAnimation): DazAnimation;
124
+ /** Number of captured frames. */
125
+ get frameCount(): number;
126
+ /** Number of bones in the skeleton at capture time. */
127
+ get boneCount(): number;
128
+ toString(): string;
129
+ }