@nebula-spatial/studio 0.0.0-stage → 0.1.1

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 (262) hide show
  1. package/README.md +206 -3
  2. package/dist/ai/contract.d.ts +73 -0
  3. package/dist/ai/host.d.ts +28 -0
  4. package/dist/asset/dependency-scan.d.ts +78 -0
  5. package/dist/asset/intake.d.ts +84 -0
  6. package/dist/asset/layout-detect.d.ts +40 -0
  7. package/dist/asset/media-type.d.ts +10 -0
  8. package/dist/asset/model-inspection.d.ts +127 -0
  9. package/dist/asset/record.d.ts +35 -0
  10. package/dist/asset/remote-asset-resolver.d.ts +36 -0
  11. package/dist/asset/repairs.d.ts +53 -0
  12. package/dist/asset/resource-locator.d.ts +15 -0
  13. package/dist/asset/revision-diff.d.ts +33 -0
  14. package/dist/asset/source-contracts.d.ts +21 -0
  15. package/dist/asset/source-paths.d.ts +15 -0
  16. package/dist/asset/usd-inspection.d.ts +39 -0
  17. package/dist/asset/usd-source-metadata.d.ts +142 -0
  18. package/dist/asset/visual-intake.d.ts +27 -0
  19. package/dist/asset/visual-record.d.ts +22 -0
  20. package/dist/asset/web-intake.d.ts +46 -0
  21. package/dist/asset-source-BExlEcRt.js +444 -0
  22. package/dist/assets/openusd_three_loader-DLiqJWUM.js +13769 -0
  23. package/dist/assets/usd-export-worker-BRxTLqer.js +182 -0
  24. package/dist/assets/usd-worker-DekqMsQv.js +1392 -0
  25. package/dist/builders-BAXRR5o5.js +1854 -0
  26. package/dist/core/asset-task.d.ts +105 -0
  27. package/dist/core/context.d.ts +23 -0
  28. package/dist/core/host.d.ts +432 -0
  29. package/dist/core/persistence-controller.d.ts +58 -0
  30. package/dist/core/plugins.d.ts +139 -0
  31. package/dist/core/scene-tree.d.ts +62 -0
  32. package/dist/core/versions.d.ts +2 -0
  33. package/dist/core/when.d.ts +13 -0
  34. package/dist/core/write-policy.d.ts +29 -0
  35. package/dist/delivery/build-plan.d.ts +2 -0
  36. package/dist/delivery/contracts.d.ts +362 -0
  37. package/dist/delivery/digest.d.ts +3 -0
  38. package/dist/delivery/evidence.d.ts +10 -0
  39. package/dist/delivery/export-evidence.d.ts +3 -0
  40. package/dist/delivery/index.d.ts +9 -0
  41. package/dist/delivery/prim-name.d.ts +17 -0
  42. package/dist/delivery/profile.d.ts +4 -0
  43. package/dist/doc/builders.d.ts +99 -0
  44. package/dist/doc/command.d.ts +195 -0
  45. package/dist/doc/domain-extensions.d.ts +34 -0
  46. package/dist/doc/node-facts.d.ts +87 -0
  47. package/dist/doc/physics-facts.d.ts +74 -0
  48. package/dist/doc/placement-policy.d.ts +71 -0
  49. package/dist/doc/random-placement.d.ts +30 -0
  50. package/dist/doc/scene-graph.d.ts +80 -0
  51. package/dist/doc/scene-regions.d.ts +29 -0
  52. package/dist/doc/schema.d.ts +452 -0
  53. package/dist/doc/task.d.ts +71 -0
  54. package/dist/doc/validate.d.ts +68 -0
  55. package/dist/editor/asset-source.d.ts +15 -0
  56. package/dist/editor/editor.d.ts +246 -0
  57. package/dist/editor/index.d.ts +22 -0
  58. package/dist/editor/shortcuts.d.ts +2 -0
  59. package/dist/editor/types.d.ts +143 -0
  60. package/dist/editor/ui-plugins.d.ts +64 -0
  61. package/dist/editor.js +1755 -0
  62. package/dist/editorial-BkAFWfbg.js +83 -0
  63. package/dist/export-evidence-DMNRhgL9.js +2705 -0
  64. package/dist/generalization/domain.d.ts +10 -0
  65. package/dist/generalization/generalization.d.ts +371 -0
  66. package/dist/generalization/index.d.ts +11 -0
  67. package/dist/generalization.js +1659 -0
  68. package/dist/history/undo-stack.d.ts +74 -0
  69. package/dist/index.d.ts +91 -0
  70. package/dist/index.js +2840 -0
  71. package/dist/mjcf-visual-Bt4bUxd1.js +72 -0
  72. package/dist/mujoco-runtime-BYZnrvbR.js +467 -0
  73. package/dist/persist/content-addressed.d.ts +11 -0
  74. package/dist/persist/create-scene-package-from-host.d.ts +7 -0
  75. package/dist/persist/indexeddb-store.d.ts +69 -0
  76. package/dist/persist/scene-file.d.ts +52 -0
  77. package/dist/persist/scene-package.d.ts +8 -0
  78. package/dist/persist/snapshot.d.ts +5 -0
  79. package/dist/physics-facts-tfQYyNTD.js +337 -0
  80. package/dist/placement-policy-DY_FNRDu.js +405 -0
  81. package/dist/ports/asset-ingestor.d.ts +41 -0
  82. package/dist/ports/asset-source.d.ts +57 -0
  83. package/dist/ports/delivery.d.ts +13 -0
  84. package/dist/ports/persistence.d.ts +29 -0
  85. package/dist/project/asset-catalog.d.ts +21 -0
  86. package/dist/project/contracts.d.ts +272 -0
  87. package/dist/project/editorial.d.ts +16 -0
  88. package/dist/project/identity.d.ts +20 -0
  89. package/dist/project/index.d.ts +9 -0
  90. package/dist/project/scene-document.d.ts +5 -0
  91. package/dist/project/source-dependencies.d.ts +7 -0
  92. package/dist/remote-asset-resolver-Cb8cfNmw.js +136 -0
  93. package/dist/scene/index.d.ts +12 -0
  94. package/dist/scene-graph-DBLKAhxa.js +681 -0
  95. package/dist/scene-session-Cy6vDJ1l.js +21981 -0
  96. package/dist/scene.js +244 -0
  97. package/dist/session-BRBrCLdd.js +963 -0
  98. package/dist/session-DI5tPJxn.js +825 -0
  99. package/dist/session-q3uuG7OP.js +296 -0
  100. package/dist/studio/delivery-catalog.d.ts +28 -0
  101. package/dist/studio/in-memory-asset-source.d.ts +15 -0
  102. package/dist/studio/index.d.ts +31 -0
  103. package/dist/studio/indexeddb-asset-source.d.ts +32 -0
  104. package/dist/studio/indexeddb-persistence.d.ts +13 -0
  105. package/dist/studio/remote-asset-importer.d.ts +56 -0
  106. package/dist/studio/source-package.d.ts +9 -0
  107. package/dist/studio/usd-export-client.d.ts +13 -0
  108. package/dist/studio/usd-export-protocol.d.ts +98 -0
  109. package/dist/studio/usd-export-worker.d.ts +1 -0
  110. package/dist/studio/usd-zip-reader.d.ts +14 -0
  111. package/dist/studio/web-asset-ingestor.d.ts +10 -0
  112. package/dist/studio/web-host.d.ts +8 -0
  113. package/dist/studio.js +5545 -0
  114. package/dist/urdf-session-CQir2nb2.js +1230 -0
  115. package/dist/usd-session-DZJnEEOs.js +7385 -0
  116. package/dist/util/asset-facts.d.ts +3 -0
  117. package/dist/util/data.d.ts +17 -0
  118. package/dist/util/diagnostics.d.ts +38 -0
  119. package/dist/util/geometry.d.ts +11 -0
  120. package/dist/util/hash.d.ts +9 -0
  121. package/dist/util/ids.d.ts +20 -0
  122. package/dist/util/math.d.ts +47 -0
  123. package/dist/util/ply-metadata.d.ts +19 -0
  124. package/dist/util/studio-source.d.ts +23 -0
  125. package/dist/version.d.ts +5 -0
  126. package/dist/view/appearance.d.ts +13 -0
  127. package/dist/view/authoring-appearance.d.ts +25 -0
  128. package/dist/view/bounds-preview.d.ts +34 -0
  129. package/dist/view/bounds.d.ts +11 -0
  130. package/dist/view/camera-zoom.d.ts +3 -0
  131. package/dist/view/geometry-anchors.d.ts +20 -0
  132. package/dist/view/gizmo-appearance.d.ts +5 -0
  133. package/dist/view/gizmo.d.ts +81 -0
  134. package/dist/view/group-selection.d.ts +13 -0
  135. package/dist/view/node-features.d.ts +39 -0
  136. package/dist/view/picking.d.ts +49 -0
  137. package/dist/view/placement.d.ts +48 -0
  138. package/dist/view/region-editing.d.ts +25 -0
  139. package/dist/view/rotation-guide.d.ts +36 -0
  140. package/dist/view/runtime-capabilities.d.ts +22 -0
  141. package/dist/view/scene-session.d.ts +258 -0
  142. package/dist/view/screen-bounds.d.ts +17 -0
  143. package/dist/view/selection-transform.d.ts +20 -0
  144. package/dist/wasm-module-DZn2AM1W.js +13 -0
  145. package/dist/xacro-DLRXyk60.js +76 -0
  146. package/node_modules/@nebula-spatial/cad-loader/CHANGELOG.md +48 -0
  147. package/node_modules/@nebula-spatial/cad-loader/README.md +108 -0
  148. package/node_modules/@nebula-spatial/cad-loader/dist/core/cad-types.d.ts +26 -0
  149. package/node_modules/@nebula-spatial/cad-loader/dist/core/errors.d.ts +5 -0
  150. package/node_modules/@nebula-spatial/cad-loader/dist/core/index.d.ts +24 -0
  151. package/node_modules/@nebula-spatial/cad-loader/dist/core/index.js +2354 -0
  152. package/node_modules/@nebula-spatial/cad-loader/dist/core/parser/bin-group-reader.d.ts +9 -0
  153. package/node_modules/@nebula-spatial/cad-loader/dist/core/parser/bin-parser.d.ts +78 -0
  154. package/node_modules/@nebula-spatial/cad-loader/dist/core/parser/dxbs-sidecar.d.ts +24 -0
  155. package/node_modules/@nebula-spatial/cad-loader/dist/core/parser/geometry-segments.d.ts +20 -0
  156. package/node_modules/@nebula-spatial/cad-loader/dist/core/parser/text-roundtrip.d.ts +4 -0
  157. package/node_modules/@nebula-spatial/cad-loader/dist/core/parser/types.d.ts +81 -0
  158. package/node_modules/@nebula-spatial/cad-loader/dist/core/runtime-text-decoder.d.ts +8 -0
  159. package/node_modules/@nebula-spatial/cad-loader/dist/core/types.d.ts +153 -0
  160. package/node_modules/@nebula-spatial/cad-loader/dist/core/utils/insert-bbox.d.ts +10 -0
  161. package/node_modules/@nebula-spatial/cad-loader/dist/core/utils/viewport-rect.d.ts +21 -0
  162. package/node_modules/@nebula-spatial/cad-loader/dist/index.d.ts +36 -0
  163. package/node_modules/@nebula-spatial/cad-loader/dist/index.js +5829 -0
  164. package/node_modules/@nebula-spatial/cad-loader/dist/loader/geo-loader.d.ts +59 -0
  165. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/automatic-external-resources.d.ts +26 -0
  166. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/external-variant-sidecar-fetch.d.ts +13 -0
  167. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/flow-control.d.ts +29 -0
  168. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/frame-budget-scheduler.d.ts +21 -0
  169. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-compact-executor.d.ts +19 -0
  170. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-loader-local-adapter.d.ts +2 -0
  171. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-loader-pipeline.d.ts +92 -0
  172. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-loader-worker-adapter.d.ts +13 -0
  173. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-node-builder.d.ts +34 -0
  174. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-node-load-sink.d.ts +28 -0
  175. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-node.d.ts +304 -0
  176. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-prepare-worker-types.d.ts +94 -0
  177. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-prepare.d.ts +38 -0
  178. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/geo-prepare.worker.d.ts +1 -0
  179. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/insert-model-builder.d.ts +10 -0
  180. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/insert-runtime-geometry.d.ts +15 -0
  181. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/line-canonical.d.ts +37 -0
  182. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/line-quality.d.ts +9 -0
  183. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/prepare-credit-gate.d.ts +20 -0
  184. package/node_modules/@nebula-spatial/cad-loader/dist/loader/internal/transport.d.ts +2 -0
  185. package/node_modules/@nebula-spatial/cad-loader/dist/render-resource/cad-render-node.d.ts +80 -0
  186. package/node_modules/@nebula-spatial/cad-loader/dist/render-resource/geo-node-cad-render-node.d.ts +12 -0
  187. package/node_modules/@nebula-spatial/cad-loader/dist/scene/geo-cad-line-geometry.d.ts +28 -0
  188. package/node_modules/@nebula-spatial/cad-loader/dist/scene/geo-cad-line-material.d.ts +18 -0
  189. package/node_modules/@nebula-spatial/cad-loader/dist/scene/instancing/block-geometry-registry.d.ts +35 -0
  190. package/node_modules/@nebula-spatial/cad-loader/dist/scene/instancing/insert-instance-table.d.ts +23 -0
  191. package/node_modules/@nebula-spatial/cad-loader/dist/scene/instancing/viewport-instance-presenter.d.ts +66 -0
  192. package/node_modules/@nebula-spatial/cad-loader/dist/selection/cad-insert-selection.d.ts +35 -0
  193. package/node_modules/@nebula-spatial/cad-loader/dist/selection/cad-text-selection.d.ts +31 -0
  194. package/node_modules/@nebula-spatial/cad-loader/dist/session/annotation-idle-gate.d.ts +14 -0
  195. package/node_modules/@nebula-spatial/cad-loader/dist/session/cad-document-session.d.ts +187 -0
  196. package/node_modules/@nebula-spatial/cad-loader/dist/session/cad-font-runtime.d.ts +11 -0
  197. package/node_modules/@nebula-spatial/cad-loader/dist/session/cad-insert-id.d.ts +6 -0
  198. package/node_modules/@nebula-spatial/cad-loader/dist/session/cad-text-warmup.d.ts +38 -0
  199. package/node_modules/@nebula-spatial/cad-loader/dist/session/create-cad-document-session.d.ts +5 -0
  200. package/node_modules/@nebula-spatial/cad-loader/dist/session/load-session.d.ts +90 -0
  201. package/node_modules/@nebula-spatial/cad-loader/dist/session/viewport-coverage.d.ts +32 -0
  202. package/node_modules/@nebula-spatial/cad-loader/dist/shared/abort.d.ts +3 -0
  203. package/node_modules/@nebula-spatial/cad-loader/dist/shared/cad-display-color.d.ts +55 -0
  204. package/node_modules/@nebula-spatial/cad-loader/dist/shared/cad-load-source.d.ts +8 -0
  205. package/node_modules/@nebula-spatial/cad-loader/dist/shared/color-buffer.d.ts +6 -0
  206. package/node_modules/@nebula-spatial/cad-loader/dist/shared/constants.d.ts +11 -0
  207. package/node_modules/@nebula-spatial/cad-loader/dist/shared/display-color-buffer.d.ts +27 -0
  208. package/node_modules/@nebula-spatial/cad-loader/dist/shared/errors.d.ts +2 -0
  209. package/node_modules/@nebula-spatial/cad-loader/dist/shared/text-builder.d.ts +25 -0
  210. package/node_modules/@nebula-spatial/cad-loader/dist/shared/text-font.d.ts +12 -0
  211. package/node_modules/@nebula-spatial/cad-loader/dist/shared/types.d.ts +57 -0
  212. package/node_modules/@nebula-spatial/cad-loader/dist/shared/utils/insert-bbox.d.ts +1 -0
  213. package/node_modules/@nebula-spatial/cad-loader/dist/shared/utils/timing.d.ts +2 -0
  214. package/node_modules/@nebula-spatial/cad-loader/dist/shared/utils/viewport-rect.d.ts +1 -0
  215. package/node_modules/@nebula-spatial/cad-loader/dist/shared/viewer-theme.d.ts +2 -0
  216. package/node_modules/@nebula-spatial/cad-loader/dist/workers/geo-prepare.worker.js +2264 -0
  217. package/node_modules/@nebula-spatial/cad-loader/package.json +62 -0
  218. package/node_modules/@nebula-spatial/viewer/CHANGELOG.md +426 -0
  219. package/node_modules/@nebula-spatial/viewer/FBX-MATERIAL-CONVERSION.md +97 -0
  220. package/node_modules/@nebula-spatial/viewer/README.md +1056 -0
  221. package/node_modules/@nebula-spatial/viewer/USD-VISUAL-MATERIAL-SUPPORT.md +89 -0
  222. package/node_modules/@nebula-spatial/viewer/basis/basis_transcoder.js +19 -0
  223. package/node_modules/@nebula-spatial/viewer/basis/basis_transcoder.wasm +0 -0
  224. package/node_modules/@nebula-spatial/viewer/dist/asset-ir-DEOK9SqE.js +382 -0
  225. package/node_modules/@nebula-spatial/viewer/dist/assets/ground-grid.d.ts +6 -0
  226. package/node_modules/@nebula-spatial/viewer/dist/assets/source-types.d.ts +19 -0
  227. package/node_modules/@nebula-spatial/viewer/dist/assets/types.d.ts +393 -0
  228. package/node_modules/@nebula-spatial/viewer/dist/assets/usd-worker-Bom5cjz3.js +1392 -0
  229. package/node_modules/@nebula-spatial/viewer/dist/cad/text.d.ts +2 -0
  230. package/node_modules/@nebula-spatial/viewer/dist/cad/types.d.ts +368 -0
  231. package/node_modules/@nebula-spatial/viewer/dist/index-ByBlfVc0.js +12132 -0
  232. package/node_modules/@nebula-spatial/viewer/dist/index.d.ts +32 -0
  233. package/node_modules/@nebula-spatial/viewer/dist/index.js +26 -0
  234. package/node_modules/@nebula-spatial/viewer/dist/inspection/types.d.ts +112 -0
  235. package/node_modules/@nebula-spatial/viewer/dist/mjcf-visual-DVRa0w90.js +72 -0
  236. package/node_modules/@nebula-spatial/viewer/dist/mujoco-runtime-Dhx6Ua2u.js +463 -0
  237. package/node_modules/@nebula-spatial/viewer/dist/plugins.d.ts +179 -0
  238. package/node_modules/@nebula-spatial/viewer/dist/scene/instances.d.ts +36 -0
  239. package/node_modules/@nebula-spatial/viewer/dist/scene/types.d.ts +258 -0
  240. package/node_modules/@nebula-spatial/viewer/dist/session-B-j6KdA-.js +389 -0
  241. package/node_modules/@nebula-spatial/viewer/dist/session-B4AICTeJ.js +963 -0
  242. package/node_modules/@nebula-spatial/viewer/dist/session-BAG5cDYe.js +9153 -0
  243. package/node_modules/@nebula-spatial/viewer/dist/simulation/mujoco-runtime.d.ts +118 -0
  244. package/node_modules/@nebula-spatial/viewer/dist/simulation/mujoco-wasm-module.d.ts +11 -0
  245. package/node_modules/@nebula-spatial/viewer/dist/simulation/openusd-wasm-module.d.ts +10 -0
  246. package/node_modules/@nebula-spatial/viewer/dist/simulation/physics-runtime-state.d.ts +75 -0
  247. package/node_modules/@nebula-spatial/viewer/dist/simulation/types.d.ts +129 -0
  248. package/node_modules/@nebula-spatial/viewer/dist/simulation/usd-inspection.d.ts +66 -0
  249. package/node_modules/@nebula-spatial/viewer/dist/simulation/usd-query.d.ts +50 -0
  250. package/node_modules/@nebula-spatial/viewer/dist/simulation/usd-resource-policy.d.ts +28 -0
  251. package/node_modules/@nebula-spatial/viewer/dist/types.d.ts +278 -0
  252. package/node_modules/@nebula-spatial/viewer/dist/ui/types.d.ts +48 -0
  253. package/node_modules/@nebula-spatial/viewer/dist/urdf-session-kemAnBn8.js +3231 -0
  254. package/node_modules/@nebula-spatial/viewer/dist/usd-session-QtwGKI7v.js +6771 -0
  255. package/node_modules/@nebula-spatial/viewer/dist/version.d.ts +5 -0
  256. package/node_modules/@nebula-spatial/viewer/dist/viewer.d.ts +2 -0
  257. package/node_modules/@nebula-spatial/viewer/dist/xacro-CYTPS7mh.js +1537 -0
  258. package/node_modules/@nebula-spatial/viewer/openusd/openusd-runtime-manifest.json +15 -0
  259. package/node_modules/@nebula-spatial/viewer/openusd/openusd_probe.js +14 -0
  260. package/node_modules/@nebula-spatial/viewer/openusd/openusd_probe.wasm +0 -0
  261. package/node_modules/@nebula-spatial/viewer/package.json +66 -0
  262. package/package.json +87 -6
@@ -0,0 +1,3 @@
1
+ export declare function calculateAssetFactsHash(value: object): string;
2
+ export declare function calculateVisualAssetFactsHash(value: object): string;
3
+ export declare function normalizeAssetFacts(value: object): Record<string, unknown>;
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Structured cloning used by every layer that hands state across a boundary.
3
+ *
4
+ * Scene documents are plain JSON-compatible data by contract, so a JSON round
5
+ * trip is both sufficient and a useful invariant check: anything that cannot
6
+ * survive it does not belong in the document.
7
+ */
8
+ export declare function cloneData<T>(value: T): T;
9
+ /** Deep-freezes plain data so readers cannot mutate shared snapshots. */
10
+ export declare function deepFreeze<T>(value: T): T;
11
+ /**
12
+ * Structural equality for plain JSON data with explicitly sorted object keys,
13
+ * so two objects that differ only in key insertion order compare equal.
14
+ */
15
+ export declare function deepEqualData(a: unknown, b: unknown): boolean;
16
+ /** Stable JSON serialization: sorted keys, no whitespace, no `undefined`. */
17
+ export declare function stableStringify(value: unknown, space?: number): string;
@@ -0,0 +1,38 @@
1
+ /**
2
+ * Diagnostics model shared by scene validation, asset intake and export.
3
+ *
4
+ * `code` is a stable contract: UI groups by it and tests assert on it, the
5
+ * same way the Viewer treats `AssetWarningSnapshot` codes. Never rename a code
6
+ * once released; add a new one instead.
7
+ */
8
+ export type DiagnosticLevel = 'info' | 'warning' | 'error';
9
+ export interface Diagnostic {
10
+ readonly code: string;
11
+ readonly level: DiagnosticLevel;
12
+ readonly message: string;
13
+ /**
14
+ * The instance this diagnostic is about. Export reports must point at the
15
+ * offending object so the UI can select it (docs/sim-studio/data-model.md §7.7).
16
+ */
17
+ readonly instanceId?: string;
18
+ /** The asset this diagnostic is about, when it is asset-scoped. */
19
+ readonly assetId?: string;
20
+ /** Free-form context; fields are stable per code but not globally. */
21
+ readonly detail?: Readonly<Record<string, string | number | boolean | null>>;
22
+ }
23
+ export declare class DiagnosticBag {
24
+ private readonly entries;
25
+ add(diagnostic: Diagnostic): void;
26
+ info(code: string, message: string, detail?: Diagnostic['detail']): void;
27
+ warn(code: string, message: string, detail?: Diagnostic['detail']): void;
28
+ error(code: string, message: string, detail?: Diagnostic['detail']): void;
29
+ get size(): number;
30
+ get hasErrors(): boolean;
31
+ toArray(): Diagnostic[];
32
+ }
33
+ /** Convenience for call sites that throw on a fatal, unrepresentable state. */
34
+ export declare class SimStudioError extends Error {
35
+ readonly code: string;
36
+ readonly detail?: Diagnostic['detail'];
37
+ constructor(code: string, message: string, detail?: Diagnostic['detail']);
38
+ }
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Primitive geometry types.
3
+ *
4
+ * These live in `util` rather than `doc` because the math helpers are also used
5
+ * by `project/` and `delivery/`, and `util` must not depend on `doc` (see
6
+ * scripts/check-boundary.mjs). `doc/schema.ts` re-exports them so document code
7
+ * still reads naturally.
8
+ */
9
+ export type Vec3 = readonly [number, number, number];
10
+ /** Quaternion in `[x, y, z, w]` order. */
11
+ export type Quat = readonly [number, number, number, number];
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Deterministic JSON and SHA-256 helpers used by scene/asset identity.
3
+ *
4
+ * The implementation is synchronous so content hashes can be calculated from
5
+ * command results without turning the document model into an async API.
6
+ */
7
+ export declare function canonicalNumber(value: number): number;
8
+ export declare function stableStringify(value: unknown): string;
9
+ export declare function sha256Hex(value: string | ArrayBuffer | ArrayBufferView): string;
@@ -0,0 +1,20 @@
1
+ /** Deterministic identifier generation and stable ordering helpers. */
2
+ /**
3
+ * Crockford base32 ULID: 10 time chars + 16 random chars, lexicographically
4
+ * sortable by creation time. Generated values are still read back through the
5
+ * `id` field, so tests override them with fixed sequences where needed.
6
+ */
7
+ export declare function createUlid(now?: number): string;
8
+ /**
9
+ * Numeric-safe stable sort. `Array.prototype.sort` is stable in modern engines,
10
+ * but callers here depend on the comparator being a total order so results are
11
+ * reproducible across platforms.
12
+ */
13
+ export declare function sortStable<T>(values: readonly T[], compare: (a: T, b: T) => number): T[];
14
+ /** Lexicographic comparison that never depends on locale. */
15
+ export declare function compareStrings(a: string, b: string): number;
16
+ /**
17
+ * Rounds to a fixed number of decimals so serialized output is byte-identical
18
+ * across runs. Used for scene transforms where 6 decimals is 1 micrometre.
19
+ */
20
+ export declare function roundDecimals(value: number, decimals?: number): number;
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Minimal, dependency-free vector/quaternion math.
3
+ *
4
+ * `doc/`, `project/`, and `delivery/` must stay free of Three.js (enforced by
5
+ * scripts/check-boundary.mjs), so the handful of operations the document model
6
+ * needs live here rather than pulling in a scene graph library.
7
+ */
8
+ import type { Quat, Vec3 } from './geometry';
9
+ /** Position, rotation and scale; `doc/schema.ts` narrows this to its own type. */
10
+ export interface TransformLike {
11
+ readonly position: Vec3;
12
+ readonly rotation: Quat;
13
+ readonly scale: Vec3;
14
+ }
15
+ export declare const IDENTITY_ROTATION: Quat;
16
+ export declare const ZERO_VECTOR: Vec3;
17
+ export declare const ONE_SCALE: Vec3;
18
+ export declare function add(a: Vec3, b: Vec3): Vec3;
19
+ export declare function subtract(a: Vec3, b: Vec3): Vec3;
20
+ export declare function multiplyScalar(a: Vec3, scalar: number): Vec3;
21
+ export declare function dot(a: Vec3, b: Vec3): number;
22
+ export declare function length(a: Vec3): number;
23
+ export declare function normalize(a: Vec3): Vec3;
24
+ export declare function quaternionLength(q: Quat): number;
25
+ /** Normalizes a quaternion; returns identity when the input is degenerate. */
26
+ export declare function normalizeQuaternion(q: Quat): Quat;
27
+ /** Hamilton product, `a * b`, matching Three.js `Quaternion.multiply`. */
28
+ export declare function multiplyQuat(a: Quat, b: Quat): Quat;
29
+ export declare function dotQuat(a: Quat, b: Quat): number;
30
+ /** Negates when needed so the shortest arc is taken. */
31
+ export declare function ensureShortestArc(from: Quat, to: Quat): Quat;
32
+ /** Rotates a vector by a quaternion. */
33
+ export declare function rotateVector(q: Quat, v: Vec3): Vec3;
34
+ /** Yaw around world Z, in radians, expressed as a unit quaternion. */
35
+ export declare function quatFromYaw(yawRadians: number): Quat;
36
+ /**
37
+ * Shortest-arc rotation mapping local +Z to a normalized parent-space direction.
38
+ * The +Z and -Z cases are fixed so persisted documents stay deterministic.
39
+ */
40
+ export declare function quatFromLocalUp(direction: Vec3): Quat;
41
+ /** Extracts the yaw component of a Z-up rotation, in radians. */
42
+ export declare function quatToYaw(q: Quat): number;
43
+ export declare function transformsEqual(a: TransformLike, b: TransformLike): boolean;
44
+ export declare function vec3Equal(a: Vec3, b: Vec3): boolean;
45
+ export declare function quatEqual(a: Quat, b: Quat): boolean;
46
+ /** True when every axis has the same magnitude. */
47
+ export declare function isUniformScale(scale: Vec3, tolerance?: number): boolean;
@@ -0,0 +1,19 @@
1
+ export type PlyContentKind = 'ply-mesh' | 'ply-point-cloud' | 'gaussian-ply' | 'unsupported';
2
+ export interface PlyHeaderMetadata {
3
+ readonly format: string | null;
4
+ readonly vertexCount: number;
5
+ readonly faceCount: number;
6
+ readonly properties: readonly string[];
7
+ readonly elements: readonly string[];
8
+ }
9
+ export interface PlyContentMetadata {
10
+ readonly kind: PlyContentKind;
11
+ readonly reason: string;
12
+ readonly ply?: PlyHeaderMetadata;
13
+ }
14
+ /**
15
+ * Renderer-free PLY inspection used by asset intake. The Viewer has a parallel
16
+ * classifier at its rendering boundary; both intentionally dispatch from the
17
+ * same content rules without coupling the pure Studio asset layer to Three.js.
18
+ */
19
+ export declare function detectPlyContent(input: Uint8Array | ArrayBuffer): PlyContentMetadata;
@@ -0,0 +1,23 @@
1
+ /** Source bytes shared by persistence and asset intake boundaries. */
2
+ /**
3
+ * Canonical identity for a source resource. This is the single structural
4
+ * authority shared by the scene schema, source bundles and persistence.
5
+ */
6
+ export type StudioAssetResourceLocator = {
7
+ readonly kind: 'package-path';
8
+ readonly path: string;
9
+ } | {
10
+ readonly kind: 'remote-url';
11
+ readonly url: string;
12
+ };
13
+ export interface StudioSourceFile {
14
+ readonly locator: StudioAssetResourceLocator;
15
+ readonly blob: Blob;
16
+ }
17
+ export interface StudioSourceBundle {
18
+ readonly assetId: string;
19
+ readonly entryLocator: StudioAssetResourceLocator;
20
+ readonly files: readonly StudioSourceFile[];
21
+ }
22
+ export declare function studioSourceLocatorPath(locator: StudioAssetResourceLocator): string;
23
+ export declare function studioSourceBundleEntryPath(bundle: StudioSourceBundle): string;
@@ -0,0 +1,5 @@
1
+ /**
2
+ * Sim Studio 版本号。必须与 package.json 的 version 保持一致,
3
+ * check-boundary 脚本会在构建前校验两者是否漂移。
4
+ */
5
+ export declare const simStudioVersion = "0.1.1";
@@ -0,0 +1,13 @@
1
+ import type { Object3D } from 'three';
2
+ import type { SceneAppearance } from '../doc/schema';
3
+ /**
4
+ * Clones each distinct source material once per instance. Clearing an override,
5
+ * removing/replacing an instance or disposing the bridge restores the exact
6
+ * original references before the Viewer releases the asset and its textures.
7
+ */
8
+ export declare class InstanceAppearance {
9
+ private readonly instances;
10
+ apply(id: string, root: Object3D, overrides: SceneAppearance | undefined): void;
11
+ remove(id: string): void;
12
+ dispose(): void;
13
+ }
@@ -0,0 +1,25 @@
1
+ import { Box3Helper, Object3D } from 'three';
2
+ import type { TransformControls } from 'three/examples/jsm/controls/TransformControls.js';
3
+ /** Use saturated axis colors and translucent handles without changing pickers. */
4
+ export declare function styleTransformControls(controls: TransformControls, variant?: 'default' | 'horizontal-rotation'): void;
5
+ /** Box3Helper bounds with a consistent screen-space selection stroke. */
6
+ export declare class SelectionBox extends Box3Helper {
7
+ private readonly stroke;
8
+ private readonly localBoundsMatrix;
9
+ private readonly parentInverse;
10
+ constructor(color: number, options?: {
11
+ readonly linewidth?: number;
12
+ readonly opacity?: number;
13
+ });
14
+ /** Keep the bounds in instance space, then follow its complete world matrix. */
15
+ updateFromObject(object: Object3D): void;
16
+ /**
17
+ * Translation-only updates reuse the measured instance-local box and only
18
+ * refresh its world matrix. This keeps high-frequency drags in sync without
19
+ * walking every mesh and recomputing each geometry bound.
20
+ */
21
+ followObject(object: Object3D): void;
22
+ setColor(color: number): void;
23
+ updateMatrixWorld(force?: boolean): void;
24
+ dispose(): void;
25
+ }
@@ -0,0 +1,34 @@
1
+ import type { Vec3 } from '../doc/schema';
2
+ export interface StudioBoundsPreviewDimensions {
3
+ readonly length: number;
4
+ readonly width: number;
5
+ readonly height: number;
6
+ }
7
+ export interface StudioBoundsPreviewInput {
8
+ readonly dimensions: StudioBoundsPreviewDimensions;
9
+ readonly localUpDirection?: Vec3;
10
+ }
11
+ export interface StudioBoundsPreviewOptions extends StudioBoundsPreviewInput {
12
+ readonly container: HTMLElement;
13
+ readonly showGrid?: boolean;
14
+ readonly showMeasurements?: boolean;
15
+ readonly showAxes?: boolean;
16
+ readonly signal?: AbortSignal;
17
+ }
18
+ export interface StudioBoundsPreview {
19
+ update(input: StudioBoundsPreviewInput): void;
20
+ fit(): boolean;
21
+ resize(): boolean;
22
+ render(): void;
23
+ dispose(): void;
24
+ }
25
+ /**
26
+ * Optional read-only Three.js surface for previewing a dimensional bounds box.
27
+ *
28
+ * This is deliberately separate from StudioSceneSession: it has no document,
29
+ * selection, history or write path. A host can use it for modal previews or
30
+ * omit it entirely and render its own visualization.
31
+ */
32
+ export declare function createStudioBoundsPreview(options: StudioBoundsPreviewOptions): StudioBoundsPreview;
33
+ /** @internal */
34
+ export declare function formatStudioBoundsPreviewUpDirection(direction: Vec3): string;
@@ -0,0 +1,11 @@
1
+ import { Box3, Object3D } from 'three';
2
+ /**
3
+ * Bounds of visible renderable geometry in world space.
4
+ *
5
+ * Static meshes retain the exact vertex-derived bounds, cached until their
6
+ * world transform or position data changes. Deforming meshes bypass the cache
7
+ * when a skeleton or active morph target can change their rendered vertices.
8
+ */
9
+ export declare function visibleBounds(object: Object3D): Box3;
10
+ /** Bounds in the instance coordinate frame, independent from its placement. */
11
+ export declare function visibleLocalBounds(object: Object3D): Box3;
@@ -0,0 +1,3 @@
1
+ import type { ViewerCameraSnapshot } from '@nebula-spatial/viewer';
2
+ /** Build a camera zoom without changing the current target or viewing angle. */
3
+ export declare function zoomedCameraSnapshot(snapshot: ViewerCameraSnapshot | null, direction: 'in' | 'out', factor?: number): ViewerCameraSnapshot | null;
@@ -0,0 +1,20 @@
1
+ import { Object3D } from 'three';
2
+ import type { Vec3 } from '../doc/schema';
3
+ export interface StudioNodeGeometryAnchors {
4
+ /** Arithmetic mean of authored vertex positions in source-content space. */
5
+ readonly median: Vec3 | null;
6
+ /** Area-weighted triangle centroid in source-content space. */
7
+ readonly surfaceCenterOfMass: Vec3 | null;
8
+ /** Volume-weighted triangle centroid in source-content space, with geometry fallbacks. */
9
+ readonly volumeCenterOfMass: Vec3 | null;
10
+ readonly source: 'runtime';
11
+ readonly vertexCount: number;
12
+ readonly triangleCount: number;
13
+ readonly surfaceAreaM2: number;
14
+ readonly volumeM3: number;
15
+ }
16
+ /**
17
+ * Measures visual mesh anchors lazily. The caller owns caching so this routine
18
+ * never participates in render or transform update loops.
19
+ */
20
+ export declare function measureObjectGeometryAnchors(root: Object3D, pivot: Vec3): StudioNodeGeometryAnchors;
@@ -0,0 +1,5 @@
1
+ import type { TransformControls } from 'three/examples/jsm/controls/TransformControls.js';
2
+ export declare const TRANSLATION_GIZMO_SIZE = 0.73;
3
+ export declare const HORIZONTAL_ROTATION_GIZMO_SIZE = 0.98;
4
+ /** Customize visible geometry and its matching pickers, without changing other modes. */
5
+ export declare function customizeGizmoGeometry(controls: TransformControls, variant: 'default' | 'horizontal-rotation'): void;
@@ -0,0 +1,81 @@
1
+ /**
2
+ * Gizmo maths: turning a drag into a transform.
3
+ *
4
+ * The gizmo itself lives in the host's renderer; what belongs here is the part
5
+ * that decides *what the new transform is* — axis constraint, snapping, and the
6
+ * delta maths. Keeping this renderer-free means the same rules apply to a mouse
7
+ * drag, a numeric inspector field and an AI-proposed move.
8
+ *
9
+ * Conventions follow the document contract: metres, Z-up, quaternion XYZW.
10
+ */
11
+ import type { Transform } from '../doc/schema';
12
+ export type GizmoMode = 'translate' | 'rotate' | 'scale';
13
+ export type GizmoAxis = 'x' | 'y' | 'z';
14
+ export interface SnapOptions {
15
+ /** Grid step in metres for translation. `0` disables snapping. */
16
+ readonly translate?: number;
17
+ /** Angle step in radians for rotation. `0` disables snapping. */
18
+ readonly rotate?: number;
19
+ /** Increment for scale. `0` disables snapping. */
20
+ readonly scale?: number;
21
+ }
22
+ export declare const DEFAULT_SNAP: Required<SnapOptions>;
23
+ export interface DragDelta {
24
+ /** Movement along the constrained axis, in metres (translate/scale ratio). */
25
+ readonly amount: number;
26
+ readonly axis: GizmoAxis;
27
+ }
28
+ /** Snaps a value to a step. A non-positive step means "no snapping". */
29
+ export declare function snapValue(value: number, step: number): number;
30
+ /**
31
+ * Applies a translation drag.
32
+ *
33
+ * `base` is the transform captured when the drag started, so a long drag never
34
+ * accumulates rounding error.
35
+ */
36
+ export declare function applyTranslate(base: Transform, delta: DragDelta, snap?: SnapOptions): Transform;
37
+ /** Applies a rotation drag around a single axis. */
38
+ export declare function applyRotate(base: Transform, delta: DragDelta, snap?: SnapOptions): Transform;
39
+ /** Applies a scale drag along one axis, never allowing a zero or negative scale. */
40
+ export declare function applyScale(base: Transform, delta: DragDelta, snap?: SnapOptions): Transform;
41
+ /** A candidate the dragged instance can snap onto. */
42
+ export interface SnapTarget {
43
+ readonly id: string;
44
+ /** World-space footprint of the target on the ground plane. */
45
+ readonly min: readonly [number, number];
46
+ readonly max: readonly [number, number];
47
+ }
48
+ /** Result of looking for the nearest edge the dragged instance could latch onto. */
49
+ export interface SnapCandidate {
50
+ readonly targetId: string;
51
+ /** World-space X/Y the dragged centre should take. */
52
+ readonly position: readonly [number, number];
53
+ /** Distance actually closed, for the owning host to render a hint. */
54
+ readonly distance: number;
55
+ }
56
+ /**
57
+ * Finds the closest neighbour the dragged footprint can butt against.
58
+ *
59
+ * Only edges line up, which is what a warehouse layout wants: two crates sharing a
60
+ * side, a bin flush with the workbench. The instance's own footprint is measured in
61
+ * world space, so rotation is already applied by the caller. `maxDistance` is the
62
+ * magnetic radius; nothing beyond it is offered, so a free drag stays free.
63
+ */
64
+ export declare function findSnapCandidate(footprint: {
65
+ readonly min: readonly [number, number];
66
+ readonly max: readonly [number, number];
67
+ }, targets: readonly SnapTarget[], maxDistance: number): SnapCandidate | null;
68
+ /**
69
+ * Snaps a finished transform onto the grid.
70
+ *
71
+ * TransformControls already snaps the axis being dragged, but a free (screen-space)
72
+ * drag and a multi-axis move can leave the other components off-grid, and the
73
+ * committed value is what the document and the export see. Rounding the whole
74
+ * transform here makes "吸附" a guarantee about the result, not just the preview.
75
+ */
76
+ export declare function snapTransform(transform: Transform, snap?: SnapOptions): Transform;
77
+ export declare function applyDelta(mode: GizmoMode, base: Transform, delta: DragDelta, snap?: SnapOptions): Transform;
78
+ /** Hamilton product `a * b` for XYZW quaternions. */
79
+ export declare function multiplyQuaternions(a: readonly [number, number, number, number], b: readonly [number, number, number, number]): [number, number, number, number];
80
+ /** Normalises a quaternion; returns the identity for a degenerate input. */
81
+ export declare function normalizeQuaternion(q: readonly [number, number, number, number]): [number, number, number, number];
@@ -0,0 +1,13 @@
1
+ import type { LocalTransform, SceneGroupNode, StudioEditorialState } from '../doc/schema';
2
+ import type { SelectionTransform, SelectionTransformNode } from './selection-transform';
3
+ /** A world-space capture, owned by one top-level selected node. */
4
+ export interface StudioSelectionMember extends SelectionTransformNode {
5
+ readonly rootId: string;
6
+ }
7
+ export declare function selectionRootIds(root: SceneGroupNode, ids: readonly string[]): readonly string[];
8
+ /**
9
+ * Transform selected roots with the normal multi-selection rules, then apply
10
+ * each root's exact matrix delta to its captured descendants. This preserves
11
+ * child axis orientation when a parent group receives a nonuniform scale.
12
+ */
13
+ export declare function transformGroupSelection(members: readonly StudioSelectionMember[], primaryId: string, next: LocalTransform, editorial: Readonly<Record<string, StudioEditorialState>>): readonly SelectionTransform[];
@@ -0,0 +1,39 @@
1
+ import type { SceneInstanceRuntime } from '@nebula-spatial/viewer';
2
+ import type { CoordinateSystem, SceneDocument, SceneNode } from '../doc/schema';
3
+ export type StudioNodeFeatureSource = 'authored' | 'runtime' | 'format' | 'none' | 'unknown';
4
+ /** Presence, readable data and viewport overlays are independent capabilities. */
5
+ export interface StudioNodeFeatureCapability {
6
+ /** null means inspection has not established whether the feature exists. */
7
+ readonly present: boolean | null;
8
+ /** The feature has valid data or a supported runtime implementation. */
9
+ readonly available: boolean;
10
+ /** The current scene SDK can display an overlay for this feature. */
11
+ readonly canVisualize: boolean;
12
+ readonly source: StudioNodeFeatureSource;
13
+ readonly reason: string;
14
+ }
15
+ export interface StudioNodeCoordinateCapability extends StudioNodeFeatureCapability {
16
+ readonly scene: CoordinateSystem;
17
+ readonly sourceUpAxis: 'X' | 'Y' | 'Z' | '-Y' | null;
18
+ readonly sourceMetersPerUnit: number | null;
19
+ }
20
+ export interface StudioNodeFeatures {
21
+ readonly nodeId: string;
22
+ readonly nodeType: SceneNode['nodeType'];
23
+ readonly collider: StudioNodeFeatureCapability;
24
+ readonly coordinateSystem: StudioNodeCoordinateCapability;
25
+ readonly jointAxes: StudioNodeFeatureCapability;
26
+ readonly centerOfMass: StudioNodeFeatureCapability;
27
+ readonly inertia: StudioNodeFeatureCapability;
28
+ readonly simulation: StudioNodeFeatureCapability;
29
+ }
30
+ export type StudioNodePhysicsVisualizationKey = 'collider' | 'coordinateSystem' | 'jointAxes' | 'centerOfMass' | 'inertia';
31
+ export type StudioNodePhysicsVisualization = Partial<Record<StudioNodePhysicsVisualizationKey, boolean>>;
32
+ export interface StudioNodePhysicsVisualizationResult {
33
+ readonly applied: readonly StudioNodePhysicsVisualizationKey[];
34
+ readonly pending: readonly StudioNodePhysicsVisualizationKey[];
35
+ readonly unsupported: readonly StudioNodePhysicsVisualizationKey[];
36
+ }
37
+ export type StudioNodePhysicsVisualizationState = Readonly<Record<StudioNodePhysicsVisualizationKey, boolean>>;
38
+ /** A detached snapshot; never freezes or mutates Viewer-owned runtime records. */
39
+ export declare function inspectNodeFeatures(document: SceneDocument, nodeId: string, runtime: SceneInstanceRuntime | null): StudioNodeFeatures | null;
@@ -0,0 +1,49 @@
1
+ /**
2
+ * Picking: deciding what a click means.
3
+ *
4
+ * The renderer supplies a raycast hit; this module turns it into a selection
5
+ * decision — which instance, whether the click adds to or replaces the
6
+ * selection, and what the selection is after the click. Pure functions over
7
+ * plain data, so the same rules can be unit-tested and reused by AI commands.
8
+ */
9
+ import type { StudioEditorialState } from '../doc/schema';
10
+ export type SelectionMode = 'replace' | 'add' | 'toggle';
11
+ export interface PickHit {
12
+ /** Prim/group name the renderer hit, e.g. `scene-instance:inst_abc`. */
13
+ readonly objectName: string;
14
+ /** Distance along the ray, used to pick the frontmost instance. */
15
+ readonly distance: number;
16
+ }
17
+ export interface Selection {
18
+ readonly instanceIds: readonly string[];
19
+ /** The instance whose properties the inspector shows. */
20
+ readonly primaryId: string | null;
21
+ }
22
+ export interface SelectableSceneNode {
23
+ readonly nodeId: string;
24
+ readonly visible: boolean;
25
+ }
26
+ export declare const EMPTY_SELECTION: Selection;
27
+ /** Extracts the instance id encoded in an object name, if any. */
28
+ export declare function instanceIdFromName(name: string): string | null;
29
+ /**
30
+ * Picks the frontmost instance from a list of hits.
31
+ *
32
+ * Hits are sorted by distance so selection does not depend on traversal order,
33
+ * and nested hits on the same instance collapse to that instance.
34
+ */
35
+ export declare function pickInstance(hits: readonly PickHit[]): string | null;
36
+ /**
37
+ * Computes the selection after a click.
38
+ *
39
+ * Hidden instances are not selectable. Locked instances remain selectable so
40
+ * their properties can be inspected and their lock can be released.
41
+ */
42
+ export declare function selectAt(current: Selection, hitId: string | null, mode?: SelectionMode, instances?: readonly SelectableSceneNode[], editorial?: Readonly<Record<string, StudioEditorialState>>): Selection;
43
+ /**
44
+ * Prunes a selection after instances were removed.
45
+ *
46
+ * Selection is editor-only state, but keeping dangling ids would make the
47
+ * inspector show a ghost.
48
+ */
49
+ export declare function pruneSelection(selection: Selection, remainingIds: readonly string[]): Selection;
@@ -0,0 +1,48 @@
1
+ import type { Transform } from '../doc/schema';
2
+ /** Axis-aligned bounds in world space, as reported by the renderer. */
3
+ export interface WorldBounds {
4
+ readonly min: readonly [number, number, number];
5
+ readonly max: readonly [number, number, number];
6
+ }
7
+ export interface PlacementOptions {
8
+ /** Height of the surface being dropped onto. Defaults to the site floor. */
9
+ readonly floorZ?: number;
10
+ /** Grid step for the X/Y drop point; `0` disables snapping. */
11
+ readonly snap?: number;
12
+ /** When true, the asset keeps its current Z instead of being seated. */
13
+ readonly keepHeight?: boolean;
14
+ }
15
+ /**
16
+ * Seats an object on a surface.
17
+ *
18
+ * `bounds` must be measured *with* the candidate transform already applied, so
19
+ * rotation and scale are accounted for; `restingZ` then says how far to move the
20
+ * object so its lowest point touches the floor.
21
+ */
22
+ export declare function seatOnFloor(transform: Transform, bounds: WorldBounds, options?: PlacementOptions): Transform;
23
+ /**
24
+ * Lifts an object that has gone below the floor back onto it.
25
+ *
26
+ * Dragging the gizmo downwards, or rotating a tall object past its tipping point,
27
+ * would otherwise sink it into the ground: the document allows any position, so the
28
+ * constraint belongs here. `bounds` must be measured after the candidate transform
29
+ * is applied. Returns the transform unchanged when it is already above the floor.
30
+ */
31
+ export declare function liftAboveFloor(transform: Transform, bounds: WorldBounds, floorZ?: number): Transform;
32
+ /**
33
+ * Places a dropped asset at a world point.
34
+ *
35
+ * The drop point is the object's *footprint centre* on the floor, which is what
36
+ * a user expects when dragging from the asset browser: the asset appears under
37
+ * the cursor, not offset by its pivot.
38
+ */
39
+ export declare function placeAtPoint(transform: Transform, bounds: WorldBounds, point: readonly [number, number], options?: PlacementOptions): Transform;
40
+ /**
41
+ * Whether a footprint overlaps anything already placed.
42
+ *
43
+ * Used to warn before dropping an asset inside another one; it is a hint, not a
44
+ * constraint, because overlapping is sometimes intentional (a box on a pallet).
45
+ */
46
+ export declare function footprintOverlaps(a: WorldBounds, b: WorldBounds, tolerance?: number): boolean;
47
+ /** Bounding box of a set of world bounds, or null when the list is empty. */
48
+ export declare function unionBounds(bounds: readonly WorldBounds[]): WorldBounds | null;
@@ -0,0 +1,25 @@
1
+ import type { RegionShape, StudioSceneRegionOverlay } from '../doc/scene-regions';
2
+ export type { RegionShape, StudioSceneRegionOverlay } from '../doc/scene-regions';
3
+ export type RegionHandleAxis = 'x' | 'y' | 'z';
4
+ export interface RegionShapeHandleSpec {
5
+ readonly id: string;
6
+ readonly mode: 'corner' | 'vertex' | 'axis';
7
+ readonly position: readonly [number, number, number];
8
+ readonly axis?: RegionHandleAxis;
9
+ readonly sign?: 1 | -1;
10
+ readonly index?: number;
11
+ }
12
+ /**
13
+ * Authoring handles stay in the Region shape's local frame. The renderer maps
14
+ * that frame onto the Region normal, so editing a wall or ceiling uses the
15
+ * same maths as a floor region.
16
+ */
17
+ export declare function regionShapeHandles(shape: RegionShape): readonly RegionShapeHandleSpec[];
18
+ /** Resizes a rectangle symmetrically around its local origin from a corner. */
19
+ export declare function resizeRectangleCorner(shape: RegionShape, localPoint: readonly [number, number], snapStep?: number): RegionShape;
20
+ /** Moves one polygon vertex in the Region plane while preserving Z. */
21
+ export declare function movePolygonVertex(shape: RegionShape, index: number, localPoint: readonly [number, number], snapStep?: number): RegionShape;
22
+ /** Symmetric box-face resize; `deltaMeters` is measured on the outward face axis. */
23
+ export declare function resizeBoxFace(shape: RegionShape, axis: RegionHandleAxis, deltaMeters: number, snapStep?: number): RegionShape;
24
+ export declare function sameRegionShape(a: RegionShape, b: RegionShape): boolean;
25
+ export declare function regionEnvelopeSize(region: Pick<StudioSceneRegionOverlay, 'shape'>): number;
@@ -0,0 +1,36 @@
1
+ import { Vector3 } from 'three';
2
+ export interface StudioRotationGuideGeometry {
3
+ readonly center: Vector3;
4
+ readonly axisX: Vector3;
5
+ readonly axisY: Vector3;
6
+ readonly normal: Vector3;
7
+ readonly radius: number;
8
+ readonly startAngle: number;
9
+ readonly delta: number;
10
+ readonly active: boolean;
11
+ }
12
+ export interface StudioRotationGuideFrame extends StudioRotationGuideGeometry {
13
+ readonly width: number;
14
+ readonly height: number;
15
+ readonly project: (world: Vector3) => {
16
+ readonly x: number;
17
+ readonly y: number;
18
+ };
19
+ readonly showRing: boolean;
20
+ readonly showHandle: boolean;
21
+ readonly handlePoint?: {
22
+ readonly x: number;
23
+ readonly y: number;
24
+ };
25
+ }
26
+ export interface StudioRotationGuide {
27
+ readonly element: SVGSVGElement;
28
+ readonly handleElement: HTMLButtonElement;
29
+ render(frame: StudioRotationGuideFrame): void;
30
+ hide(): void;
31
+ dispose(): void;
32
+ }
33
+ export declare function normalizeAngleDelta(from: number, to: number): number;
34
+ export declare function snapRotationDelta(delta: number, stepDegrees: number): number;
35
+ export declare function rotationGuidePoint(geometry: StudioRotationGuideGeometry, angle: number): Vector3;
36
+ export declare function createStudioRotationGuide(viewport: HTMLElement, document: Document | null): StudioRotationGuide | null;
@@ -0,0 +1,22 @@
1
+ export type StudioProjectionStatus = 'applied' | 'partial' | 'not-applied' | 'unsupported';
2
+ export interface StudioProjectionCapability {
3
+ readonly status: StudioProjectionStatus;
4
+ readonly reason: string;
5
+ }
6
+ export interface StudioRuntimeProjectionCapabilities {
7
+ readonly localWorldTransforms: StudioProjectionCapability;
8
+ readonly visibility: StudioProjectionCapability;
9
+ readonly appearance: StudioProjectionCapability;
10
+ readonly variantSelections: StudioProjectionCapability;
11
+ readonly physicsOverride: StudioProjectionCapability;
12
+ readonly physicsMaterial: StudioProjectionCapability;
13
+ readonly initialPose: StudioProjectionCapability;
14
+ readonly environment: StudioProjectionCapability;
15
+ readonly placeholder: StudioProjectionCapability;
16
+ }
17
+ /**
18
+ * Explicit boundary between values that are persisted and values the current
19
+ * browser runtime actually consumes. Update this contract with evidence when a
20
+ * projection is implemented; saving a field alone is not runtime support.
21
+ */
22
+ export declare function getStudioRuntimeProjectionCapabilities(): StudioRuntimeProjectionCapabilities;