@nova-lab/core 1.0.0-dev.19 → 1.1.1-dev.229

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 (501) hide show
  1. package/README.md +1035 -10
  2. package/THIRD_PARTY_NOTICES.md +26 -0
  3. package/dist/2d/accessibility.d.ts +2 -0
  4. package/dist/2d/accessibility.js +171 -0
  5. package/dist/2d/commands.d.ts +2 -0
  6. package/dist/2d/commands.js +80 -0
  7. package/dist/2d/effects.d.ts +10 -0
  8. package/dist/2d/effects.js +566 -0
  9. package/dist/2d/ktx2.d.ts +5 -0
  10. package/dist/2d/ktx2.js +542 -0
  11. package/dist/2d/lighting.d.ts +3 -0
  12. package/dist/2d/lighting.js +495 -0
  13. package/dist/2d/lottie.d.ts +3 -0
  14. package/dist/2d/lottie.js +254 -0
  15. package/dist/2d/meshes.d.ts +4 -0
  16. package/dist/2d/meshes.js +451 -0
  17. package/dist/2d/primitives.d.ts +3 -0
  18. package/dist/2d/primitives.js +85 -0
  19. package/dist/2d/render-textures.d.ts +3 -0
  20. package/dist/2d/render-textures.js +539 -0
  21. package/dist/2d/svg/documents.d.ts +5 -0
  22. package/dist/2d/svg/documents.js +7 -0
  23. package/dist/2d/svg/renderer.d.ts +3 -0
  24. package/dist/2d/svg/renderer.js +222 -0
  25. package/dist/2d/svg.d.ts +3 -0
  26. package/dist/2d/svg.js +4 -0
  27. package/dist/2d/tools.d.ts +2 -0
  28. package/dist/2d/tools.js +100 -0
  29. package/dist/2d/video.d.ts +5 -0
  30. package/dist/2d/video.js +90 -0
  31. package/dist/2d.d.ts +2 -0
  32. package/dist/2d.js +220 -0
  33. package/dist/3d/animation.d.ts +8 -0
  34. package/dist/3d/animation.js +1396 -0
  35. package/dist/3d/area-lights.d.ts +2 -0
  36. package/dist/3d/area-lights.js +19 -0
  37. package/dist/3d/audio.d.ts +4 -0
  38. package/dist/3d/audio.js +500 -0
  39. package/dist/3d/character.d.ts +2 -0
  40. package/dist/3d/character.js +136 -0
  41. package/dist/3d/collision.d.ts +3 -0
  42. package/dist/3d/collision.js +387 -0
  43. package/dist/3d/commands.d.ts +2 -0
  44. package/dist/3d/commands.js +108 -0
  45. package/dist/3d/controls.d.ts +8 -0
  46. package/dist/3d/controls.js +1041 -0
  47. package/dist/3d/documents.d.ts +5 -0
  48. package/dist/3d/documents.js +227 -0
  49. package/dist/3d/effects.d.ts +5 -0
  50. package/dist/3d/effects.js +1986 -0
  51. package/dist/3d/export.d.ts +4 -0
  52. package/dist/3d/export.js +347 -0
  53. package/dist/3d/fbx.d.ts +2 -0
  54. package/dist/3d/fbx.js +784 -0
  55. package/dist/3d/gltf.d.ts +2 -0
  56. package/dist/3d/gltf.js +5 -0
  57. package/dist/3d/helpers.d.ts +5 -0
  58. package/dist/3d/helpers.js +191 -0
  59. package/dist/3d/ik.d.ts +9 -0
  60. package/dist/3d/ik.js +777 -0
  61. package/dist/3d/loaders.d.ts +17 -0
  62. package/dist/3d/loaders.js +1406 -0
  63. package/dist/3d/nodes.d.ts +8 -0
  64. package/dist/3d/nodes.js +49 -0
  65. package/dist/3d/particles.d.ts +5 -0
  66. package/dist/3d/particles.js +1574 -0
  67. package/dist/3d/physics/backend.d.ts +7 -0
  68. package/dist/3d/physics/backend.js +1 -0
  69. package/dist/3d/physics/rapier.d.ts +3 -0
  70. package/dist/3d/physics/rapier.js +765 -0
  71. package/dist/3d/physics.d.ts +5 -0
  72. package/dist/3d/physics.js +3346 -0
  73. package/dist/3d/splats.d.ts +7 -0
  74. package/dist/3d/splats.js +862 -0
  75. package/dist/3d/text.d.ts +5 -0
  76. package/dist/3d/text.js +1043 -0
  77. package/dist/3d/tiles.d.ts +24 -0
  78. package/dist/3d/tiles.js +1705 -0
  79. package/dist/3d/tools.d.ts +12 -0
  80. package/dist/3d/tools.js +338 -0
  81. package/dist/3d/usdz.d.ts +2 -0
  82. package/dist/3d/usdz.js +634 -0
  83. package/dist/3d/xr.d.ts +2 -0
  84. package/dist/3d/xr.js +202 -0
  85. package/dist/3d-B4jWF8Qb.js +5591 -0
  86. package/dist/3d.d.ts +40 -0
  87. package/dist/3d.js +44 -0
  88. package/dist/Capsule-BFVpZfvc.js +44 -0
  89. package/dist/Clip-CAN7t03k.js +204 -0
  90. package/dist/Color-vuv9UnoY.js +34 -0
  91. package/dist/DeformedMesh-CPi0P_vc.js +280 -0
  92. package/dist/Document-DCVEZSvM.js +415 -0
  93. package/dist/Errors-B2ekO9bZ.js +30 -0
  94. package/dist/Features-BsjmePtc.js +557 -0
  95. package/dist/GLTFResourceIO-CYJyCUTt.js +124 -0
  96. package/dist/GPUParticleState-CQlNpoDa.js +545 -0
  97. package/dist/Geometry-DytO490z.js +227 -0
  98. package/dist/Inflate-DWw0V-Up.js +42 -0
  99. package/dist/InstancedMesh-DPrgrw5z.js +527 -0
  100. package/dist/Limits-Bw5XQdFr.js +20 -0
  101. package/dist/LineHelper-Ad0z9uDi.js +131 -0
  102. package/dist/LoaderIO-BwrM84OM.js +114 -0
  103. package/dist/Material-BpfLPmK9.js +777 -0
  104. package/dist/Mesh-BaRxAAJq.js +209 -0
  105. package/dist/Node-QfgAE2_v.js +877 -0
  106. package/dist/NovaAssetRegistry-p2QlCwvT.js +1168 -0
  107. package/dist/NovaNode-CBZ-Ol-W.js +2016 -0
  108. package/dist/NovaRenderCommandWriter-CWQRa42y.js +1949 -0
  109. package/dist/NovaTextSelectionService-CipuujCT.js +18526 -0
  110. package/dist/NovaWebGLProgram-BO250QNF.js +97 -0
  111. package/dist/Options-CajE7LLJ.js +15 -0
  112. package/dist/PolygonMesh-D4PnnfIo.js +657 -0
  113. package/dist/Ready-BzyhRtjD.js +21 -0
  114. package/dist/Scene-CDfNgf9I.js +911 -0
  115. package/dist/Shader-b6_HDndT.js +48 -0
  116. package/dist/SplatShader-wJ6GJ3vo.js +130 -0
  117. package/dist/Texture-dTKMlTpK.js +267 -0
  118. package/dist/TextureLoader-CfDzdy2m.js +411 -0
  119. package/dist/Textures-CGL4Kf-8.js +651 -0
  120. package/dist/ToneMapping-D9IWvN0u.js +46 -0
  121. package/dist/WebGPURenderer-DjD0IxVC.js +4921 -0
  122. package/dist/ZipReader-C-MSEsSr.js +84 -0
  123. package/dist/core.js +218 -24024
  124. package/dist/domain/types/base.types.d.ts +18 -9
  125. package/dist/domain/types/component.types.d.ts +5 -5
  126. package/dist/domain/types/cursor.types.d.ts +1 -1
  127. package/dist/domain/types/diagnostics.types.d.ts +2 -0
  128. package/dist/domain/types/export.types.d.ts +2 -2
  129. package/dist/domain/types/hit-test.types.d.ts +1 -1
  130. package/dist/domain/types/motion.types.d.ts +2 -2
  131. package/dist/domain/types/renderer.types.d.ts +88 -4
  132. package/dist/domain/types/rendering/index.d.ts +29 -4
  133. package/dist/domain/types/sound.types.d.ts +1 -1
  134. package/dist/domain/types/theme.types.d.ts +1 -1
  135. package/dist/domain/utils/bounds.d.ts +1 -1
  136. package/dist/domain/utils/nova-text.d.ts +9 -0
  137. package/dist/domain/utils/schemaBounds.d.ts +2 -2
  138. package/dist/export-svg-document-ChaNXMaG.js +668 -0
  139. package/dist/features/3d/Errors.d.ts +57 -0
  140. package/dist/features/3d/Nova3DApp.d.ts +429 -0
  141. package/dist/features/3d/animation/Animator.d.ts +260 -0
  142. package/dist/features/3d/animation/Clip.d.ts +74 -0
  143. package/dist/features/3d/animation/Graph.d.ts +158 -0
  144. package/dist/features/3d/animation/Mask.d.ts +40 -0
  145. package/dist/features/3d/audio/Audio.d.ts +114 -0
  146. package/dist/features/3d/audio/Sound.d.ts +133 -0
  147. package/dist/features/3d/character/CharacterController.d.ts +61 -0
  148. package/dist/features/3d/collision/Capsule.d.ts +25 -0
  149. package/dist/features/3d/collision/Octree.d.ts +94 -0
  150. package/dist/features/3d/controls/CameraMotionControls.d.ts +154 -0
  151. package/dist/features/3d/controls/CameraOrientation.d.ts +47 -0
  152. package/dist/features/3d/controls/OrbitControls.d.ts +73 -0
  153. package/dist/features/3d/controls/PointerGesture.d.ts +25 -0
  154. package/dist/features/3d/controls/PointerLock.d.ts +36 -0
  155. package/dist/features/3d/controls/Snapping.d.ts +32 -0
  156. package/dist/features/3d/controls/TransformGizmo.d.ts +79 -0
  157. package/dist/features/3d/deformation/DeformationGPU.d.ts +52 -0
  158. package/dist/features/3d/deformation/DeformationShader.d.ts +2 -0
  159. package/dist/features/3d/deformation/DeformedMesh.d.ts +36 -0
  160. package/dist/features/3d/deformation/GeometryDeformation.d.ts +25 -0
  161. package/dist/features/3d/documents/Document.d.ts +59 -0
  162. package/dist/features/3d/documents/DocumentCommands.d.ts +45 -0
  163. package/dist/features/3d/documents/DocumentSchema.d.ts +18 -0
  164. package/dist/features/3d/documents/DocumentTransform.d.ts +4 -0
  165. package/dist/features/3d/documents/DocumentTypes.d.ts +182 -0
  166. package/dist/features/3d/documents/DocumentValidation.d.ts +18 -0
  167. package/dist/features/3d/documents/Projection.d.ts +65 -0
  168. package/dist/features/3d/effects/CubeLUT.d.ts +24 -0
  169. package/dist/features/3d/effects/Effects.d.ts +32 -0
  170. package/dist/features/3d/effects/EffectsGPU.d.ts +80 -0
  171. package/dist/features/3d/effects/EffectsPlan.d.ts +268 -0
  172. package/dist/features/3d/effects/EffectsShaders.d.ts +35 -0
  173. package/dist/features/3d/export/GLTFExporter.d.ts +49 -0
  174. package/dist/features/3d/export/ThreeMFExporter.d.ts +19 -0
  175. package/dist/features/3d/export/ZipWriter.d.ts +9 -0
  176. package/dist/features/3d/fbx/FBXLoader.d.ts +26 -0
  177. package/dist/features/3d/fbx/FBXParser.d.ts +35 -0
  178. package/dist/features/3d/fbx/FBXScene.d.ts +20 -0
  179. package/dist/features/3d/gltf/GLTFLoader.d.ts +16 -0
  180. package/dist/features/3d/gltf/GLTFTypes.d.ts +64 -0
  181. package/dist/features/3d/gltf/services/GLTFBinary.d.ts +21 -0
  182. package/dist/features/3d/gltf/services/GLTFGeometry.d.ts +14 -0
  183. package/dist/features/3d/gltf/services/GLTFResourceIO.d.ts +64 -0
  184. package/dist/features/3d/helpers/LineHelper.d.ts +51 -0
  185. package/dist/features/3d/helpers/StaticHelpers.d.ts +47 -0
  186. package/dist/features/3d/helpers/TrackedHelpers.d.ts +84 -0
  187. package/dist/features/3d/ik/ChainIK.d.ts +44 -0
  188. package/dist/features/3d/ik/IKChain.d.ts +92 -0
  189. package/dist/features/3d/ik/IKMath.d.ts +49 -0
  190. package/dist/features/3d/ik/IKSolver.d.ts +97 -0
  191. package/dist/features/3d/ik/LookAtIK.d.ts +58 -0
  192. package/dist/features/3d/ik/TwoBoneIK.d.ts +57 -0
  193. package/dist/features/3d/import/ImportAnimation.d.ts +20 -0
  194. package/dist/features/3d/import/ImportMath.d.ts +42 -0
  195. package/dist/features/3d/import/ImportedModel.d.ts +135 -0
  196. package/dist/features/3d/import/Inflate.d.ts +5 -0
  197. package/dist/features/3d/import/ModelAsset.d.ts +149 -0
  198. package/dist/features/3d/import/PolygonMesh.d.ts +54 -0
  199. package/dist/features/3d/lights/AreaLightTables.d.ts +8 -0
  200. package/dist/features/3d/lights/AreaLights.d.ts +11 -0
  201. package/dist/features/3d/loaders/EXRCompression.d.ts +13 -0
  202. package/dist/features/3d/loaders/EXRLoader.d.ts +39 -0
  203. package/dist/features/3d/loaders/HDRLoader.d.ts +26 -0
  204. package/dist/features/3d/loaders/Limits.d.ts +70 -0
  205. package/dist/features/3d/loaders/LoaderBuffers.d.ts +42 -0
  206. package/dist/features/3d/loaders/LoaderIO.d.ts +81 -0
  207. package/dist/features/3d/loaders/LoaderModel.d.ts +80 -0
  208. package/dist/features/3d/loaders/LoaderText.d.ts +27 -0
  209. package/dist/features/3d/loaders/MTLLoader.d.ts +105 -0
  210. package/dist/features/3d/loaders/OBJLoader.d.ts +70 -0
  211. package/dist/features/3d/loaders/PLYLoader.d.ts +47 -0
  212. package/dist/features/3d/loaders/STLLoader.d.ts +27 -0
  213. package/dist/features/3d/model/Camera.d.ts +33 -0
  214. package/dist/features/3d/model/Environment.d.ts +31 -0
  215. package/dist/features/3d/model/Geometry.d.ts +59 -0
  216. package/dist/features/3d/model/InstancedMesh.d.ts +134 -0
  217. package/dist/features/3d/model/LOD.d.ts +31 -0
  218. package/dist/features/3d/model/Light.d.ts +200 -0
  219. package/dist/features/3d/model/Material.d.ts +308 -0
  220. package/dist/features/3d/model/MaterialExtensions.d.ts +200 -0
  221. package/dist/features/3d/model/Mesh.d.ts +92 -0
  222. package/dist/features/3d/model/Node.d.ts +87 -0
  223. package/dist/features/3d/model/ReflectionProbe.d.ts +45 -0
  224. package/dist/features/3d/model/RenderTarget.d.ts +41 -0
  225. package/dist/features/3d/model/Scene.d.ts +173 -0
  226. package/dist/features/3d/model/Texture.d.ts +143 -0
  227. package/dist/features/3d/nodes/Nodes.d.ts +8 -0
  228. package/dist/features/3d/nodes/ShaderNode.d.ts +240 -0
  229. package/dist/features/3d/particles/GPUParticleSchedule.d.ts +67 -0
  230. package/dist/features/3d/particles/GPUParticleShaders.d.ts +19 -0
  231. package/dist/features/3d/particles/GPUParticleState.d.ts +106 -0
  232. package/dist/features/3d/particles/GPUParticleSystem.d.ts +192 -0
  233. package/dist/features/3d/particles/ParticleCurves.d.ts +34 -0
  234. package/dist/features/3d/particles/ParticleOptions.d.ts +78 -0
  235. package/dist/features/3d/particles/ParticleSystem.d.ts +368 -0
  236. package/dist/features/3d/physics/PhysicsBackend.d.ts +352 -0
  237. package/dist/features/3d/physics/PhysicsDebug.d.ts +24 -0
  238. package/dist/features/3d/physics/PhysicsWorld.d.ts +352 -0
  239. package/dist/features/3d/physics/basic/BasicCollision.d.ts +75 -0
  240. package/dist/features/3d/physics/basic/BasicPhysics.d.ts +24 -0
  241. package/dist/features/3d/physics/basic/BasicShapes.d.ts +103 -0
  242. package/dist/features/3d/physics/rapier/ContactBuffer.d.ts +32 -0
  243. package/dist/features/3d/physics/rapier/RapierBackend.d.ts +17 -0
  244. package/dist/features/3d/physics/rapier/RapierShapes.d.ts +4 -0
  245. package/dist/features/3d/physics/rapier/RapierWorld.d.ts +198 -0
  246. package/dist/features/3d/physics/rapier/Validation.d.ts +8 -0
  247. package/dist/features/3d/services/Background.d.ts +22 -0
  248. package/dist/features/3d/services/BasicShader.d.ts +55 -0
  249. package/dist/features/3d/services/ClusteredLights.d.ts +69 -0
  250. package/dist/features/3d/services/DrawOrder.d.ts +37 -0
  251. package/dist/features/3d/services/EffectsProcessor.d.ts +38 -0
  252. package/dist/features/3d/services/EnvironmentBRDF.d.ts +35 -0
  253. package/dist/features/3d/services/EnvironmentMaps.d.ts +55 -0
  254. package/dist/features/3d/services/FogShader.d.ts +6 -0
  255. package/dist/features/3d/services/Frustum.d.ts +7 -0
  256. package/dist/features/3d/services/GLState.d.ts +86 -0
  257. package/dist/features/3d/services/GPUPicker.d.ts +31 -0
  258. package/dist/features/3d/services/InstanceShader.d.ts +3 -0
  259. package/dist/features/3d/services/LineProgram.d.ts +32 -0
  260. package/dist/features/3d/services/PBRProgram.d.ts +115 -0
  261. package/dist/features/3d/services/Renderer.d.ts +50 -0
  262. package/dist/features/3d/services/Shader.d.ts +22 -0
  263. package/dist/features/3d/services/ShaderProgram.d.ts +38 -0
  264. package/dist/features/3d/services/ShadowMaps.d.ts +97 -0
  265. package/dist/features/3d/services/SpatialIndex.d.ts +16 -0
  266. package/dist/features/3d/services/TextureLoader.d.ts +40 -0
  267. package/dist/features/3d/services/TextureMipmaps.d.ts +42 -0
  268. package/dist/features/3d/services/ToneMapping.d.ts +12 -0
  269. package/dist/features/3d/services/WebGLRenderer.d.ts +261 -0
  270. package/dist/features/3d/splats/SplatData.d.ts +136 -0
  271. package/dist/features/3d/splats/SplatLoaders.d.ts +64 -0
  272. package/dist/features/3d/splats/SplatShader.d.ts +14 -0
  273. package/dist/features/3d/splats/SplatSort.d.ts +69 -0
  274. package/dist/features/3d/splats/Splats.d.ts +116 -0
  275. package/dist/features/3d/text/FontAtlas.d.ts +246 -0
  276. package/dist/features/3d/text/SDF.d.ts +28 -0
  277. package/dist/features/3d/text/Text.d.ts +179 -0
  278. package/dist/features/3d/text/TextLayout.d.ts +73 -0
  279. package/dist/features/3d/text/TextShader.d.ts +12 -0
  280. package/dist/features/3d/tiles/BoundingVolume.d.ts +43 -0
  281. package/dist/features/3d/tiles/Geodesy.d.ts +106 -0
  282. package/dist/features/3d/tiles/GlobeControls.d.ts +147 -0
  283. package/dist/features/3d/tiles/TileContent.d.ts +35 -0
  284. package/dist/features/3d/tiles/TileFormats.d.ts +77 -0
  285. package/dist/features/3d/tiles/Tiles3D.d.ts +236 -0
  286. package/dist/features/3d/tiles/Tileset.d.ts +81 -0
  287. package/dist/features/3d/tools/BatchedMesh.d.ts +74 -0
  288. package/dist/features/3d/tools/CanvasSurface.d.ts +81 -0
  289. package/dist/features/3d/tools/Color.d.ts +11 -0
  290. package/dist/features/3d/tools/MergeGeometries.d.ts +22 -0
  291. package/dist/features/3d/tools/Options.d.ts +15 -0
  292. package/dist/features/3d/tools/Polyhedra.d.ts +30 -0
  293. package/dist/features/3d/tools/PrimitiveBuffers.d.ts +42 -0
  294. package/dist/features/3d/tools/Primitives.d.ts +164 -0
  295. package/dist/features/3d/tools/Ready.d.ts +12 -0
  296. package/dist/features/3d/tools/SpatialMath.d.ts +57 -0
  297. package/dist/features/3d/tools/SphericalHarmonics.d.ts +9 -0
  298. package/dist/features/3d/tools/math/mat3.d.ts +7 -0
  299. package/dist/features/3d/tools/math/mat4.d.ts +19 -0
  300. package/dist/features/3d/tools/math/quat.d.ts +6 -0
  301. package/dist/features/3d/tools/math/vec3.d.ts +16 -0
  302. package/dist/features/3d/tools/math/vec4.d.ts +5 -0
  303. package/dist/features/3d/types.d.ts +359 -0
  304. package/dist/features/3d/usdz/USDAParser.d.ts +50 -0
  305. package/dist/features/3d/usdz/USDScene.d.ts +20 -0
  306. package/dist/features/3d/usdz/USDZLoader.d.ts +27 -0
  307. package/dist/features/3d/usdz/ZipReader.d.ts +16 -0
  308. package/dist/features/3d/webgpu/Backend.d.ts +40 -0
  309. package/dist/features/3d/webgpu/BasicShader.d.ts +10 -0
  310. package/dist/features/3d/webgpu/Constants.d.ts +32 -0
  311. package/dist/features/3d/webgpu/Deformation.d.ts +71 -0
  312. package/dist/features/3d/webgpu/Environment.d.ts +66 -0
  313. package/dist/features/3d/webgpu/Features.d.ts +68 -0
  314. package/dist/features/3d/webgpu/Layouts.d.ts +27 -0
  315. package/dist/features/3d/webgpu/Lines.d.ts +40 -0
  316. package/dist/features/3d/webgpu/LitExtras.d.ts +46 -0
  317. package/dist/features/3d/webgpu/LitFeatures.d.ts +41 -0
  318. package/dist/features/3d/webgpu/LitScene.d.ts +60 -0
  319. package/dist/features/3d/webgpu/LitShader.d.ts +68 -0
  320. package/dist/features/3d/webgpu/Particles.d.ts +114 -0
  321. package/dist/features/3d/webgpu/Picking.d.ts +59 -0
  322. package/dist/features/3d/webgpu/PipelineKey.d.ts +33 -0
  323. package/dist/features/3d/webgpu/Points.d.ts +41 -0
  324. package/dist/features/3d/webgpu/Probes.d.ts +45 -0
  325. package/dist/features/3d/webgpu/ShaderChunks.d.ts +18 -0
  326. package/dist/features/3d/webgpu/ShaderMaterial.d.ts +57 -0
  327. package/dist/features/3d/webgpu/ShaderMaterialSource.d.ts +5 -0
  328. package/dist/features/3d/webgpu/Shadows.d.ts +49 -0
  329. package/dist/features/3d/webgpu/Splats.d.ts +47 -0
  330. package/dist/features/3d/webgpu/Textures.d.ts +52 -0
  331. package/dist/features/3d/webgpu/Transmission.d.ts +30 -0
  332. package/dist/features/3d/webgpu/UniformLayout.d.ts +30 -0
  333. package/dist/features/3d/webgpu/UtilityShaders.d.ts +38 -0
  334. package/dist/features/3d/webgpu/WebGPURenderer.d.ts +327 -0
  335. package/dist/features/3d/webgpu/effects/EffectsShaders.d.ts +74 -0
  336. package/dist/features/3d/webgpu/effects/WebGPUEffects.d.ts +140 -0
  337. package/dist/features/3d/xr/XR.d.ts +100 -0
  338. package/dist/gltf-By-n0qEg.js +960 -0
  339. package/dist/index.d.ts +86 -81
  340. package/dist/model/document-actions/document-commands.d.ts +18 -0
  341. package/dist/model/documents/svg/create-svg-document-renderer.d.ts +32 -0
  342. package/dist/model/documents/svg/export-svg-document.d.ts +5 -0
  343. package/dist/model/documents/svg/import-svg-document.d.ts +6 -0
  344. package/dist/model/documents/svg/svg-document.types.d.ts +111 -0
  345. package/dist/model/documents/svg/svg-values.d.ts +16 -0
  346. package/dist/model/documents/svg/svg-xml.d.ts +18 -0
  347. package/dist/model/input/NovaInputProxy_Adapter.d.ts +2 -1
  348. package/dist/model/input/NovaInputValidationController.d.ts +1 -1
  349. package/dist/model/input/NovaTextInputController.d.ts +1 -1
  350. package/dist/model/input/NovaTextLayoutEngine.d.ts +2 -6
  351. package/dist/model/input/index.d.ts +7 -7
  352. package/dist/model/input/nova-input.types.d.ts +1 -1
  353. package/dist/model/lighting/LightingRenderer2D.d.ts +58 -0
  354. package/dist/model/lighting/NovaLighting2D.d.ts +56 -0
  355. package/dist/model/lighting/lighting-shaders.d.ts +3 -0
  356. package/dist/model/lighting/lighting-state.d.ts +27 -0
  357. package/dist/model/lighting/lighting.types.d.ts +107 -0
  358. package/dist/model/lottie/LottieNode.d.ts +4 -0
  359. package/dist/model/lottie/lottie.types.d.ts +83 -0
  360. package/dist/model/lottie/prepare-lottie.d.ts +3 -0
  361. package/dist/model/lottie/sample-position.d.ts +9 -0
  362. package/dist/model/motion/NovaMotionEngine.d.ts +3 -3
  363. package/dist/model/motion/nova-motion-easing.d.ts +1 -1
  364. package/dist/model/motion/nova-motion-interpolation.d.ts +1 -1
  365. package/dist/model/motion/nova-motion-presets.d.ts +2 -2
  366. package/dist/model/motion/nova-motion-timeline.d.ts +1 -1
  367. package/dist/model/platform/NovaCanvas.d.ts +7 -6
  368. package/dist/model/primitives/NovaPrimitiveUnsupportedError.d.ts +13 -0
  369. package/dist/model/primitives/definePrimitive.d.ts +5 -0
  370. package/dist/model/primitives/primitive.types.d.ts +28 -0
  371. package/dist/model/render/backends/canvas2d/NovaCanvas2DTargetManager.d.ts +3 -3
  372. package/dist/model/render/backends/canvas2d/NovaRenderer2D.d.ts +61 -15
  373. package/dist/model/render/backends/canvas2d/nova-canvas-blend.d.ts +5 -0
  374. package/dist/model/render/backends/nova-render-backend-factory.d.ts +6 -6
  375. package/dist/model/render/backends/nova-render-backend.d.ts +8 -2
  376. package/dist/model/render/backends/webgl/NovaRendererWebGL.d.ts +32 -11
  377. package/dist/model/render/backends/webgl/NovaStreamCacheIdleLedger.d.ts +12 -1
  378. package/dist/model/render/backends/webgl/NovaWebGLBatcher.d.ts +1 -1
  379. package/dist/model/render/backends/webgl/NovaWebGLCircleImagePass.d.ts +23 -0
  380. package/dist/model/render/backends/webgl/NovaWebGLCompositionPass.d.ts +9 -0
  381. package/dist/model/render/backends/webgl/NovaWebGLDevice.d.ts +3 -1
  382. package/dist/model/render/backends/webgl/NovaWebGLDiagnostics.d.ts +1 -1
  383. package/dist/model/render/backends/webgl/NovaWebGLFrameRenderer.d.ts +162 -53
  384. package/dist/model/render/backends/webgl/NovaWebGLPathClipPass.d.ts +13 -0
  385. package/dist/model/render/backends/webgl/NovaWebGLPathUnion.d.ts +23 -0
  386. package/dist/model/render/compiler/NovaRenderBuilder.d.ts +24 -10
  387. package/dist/model/render/compiler/NovaRenderCommandWriter.d.ts +10 -5
  388. package/dist/model/render/compiler/NovaRenderCompiler.d.ts +7 -6
  389. package/dist/model/render/compiler/NovaRenderFrameBuilder.d.ts +4 -3
  390. package/dist/model/render/effects/blur.d.ts +8 -0
  391. package/dist/model/render/effects/color-matrix.d.ts +8 -0
  392. package/dist/model/render/effects/drop-shadow.d.ts +18 -0
  393. package/dist/model/render/effects/nova-effect-registry.d.ts +66 -0
  394. package/dist/model/render/effects/nova-gaussian-kernel.d.ts +7 -0
  395. package/dist/model/render/effects/nova-gaussian-textures.d.ts +11 -0
  396. package/dist/model/render/effects/shader-effect.d.ts +64 -0
  397. package/dist/model/render/geometry/nova-alpha-mask.d.ts +5 -0
  398. package/dist/model/render/geometry/nova-composition.d.ts +9 -0
  399. package/dist/model/render/geometry/nova-node-clip.d.ts +17 -0
  400. package/dist/model/render/geometry/nova-path-geometry.d.ts +24 -0
  401. package/dist/model/render/geometry/nova-path-tessellation.d.ts +7 -0
  402. package/dist/model/render/geometry/nova-polygon-triangulation.d.ts +1 -1
  403. package/dist/model/render/graph/NovaRectBatchBuffer.d.ts +58 -0
  404. package/dist/model/render/graph/NovaRenderGraph.d.ts +40 -6
  405. package/dist/model/render/graph/NovaRenderHitIndex.d.ts +1 -1
  406. package/dist/model/render/graph/nova-auto-rect.d.ts +1 -1
  407. package/dist/model/render/graph/nova-linear-rect-repack.d.ts +4 -4
  408. package/dist/model/render/graph/nova-linear-rect-transition.d.ts +2 -2
  409. package/dist/model/render/graph/nova-render-culling.d.ts +2 -2
  410. package/dist/model/render/graph/nova-render-dirty-items.d.ts +1 -1
  411. package/dist/model/render/graph/nova-render-group.d.ts +1 -1
  412. package/dist/model/render/graph/nova-render-item.d.ts +2 -2
  413. package/dist/model/render/graph/nova-render-layer.d.ts +1 -1
  414. package/dist/model/render/graph/nova-render-payload-snapshot.d.ts +3 -1
  415. package/dist/model/render/graph/nova-render-program.d.ts +5 -3
  416. package/dist/model/render/graph/nova-render-sequence.d.ts +1 -1
  417. package/dist/model/render/graph/nova-render-stream.d.ts +2 -2
  418. package/dist/model/render/ktx2/BasisSession.d.ts +45 -0
  419. package/dist/model/render/ktx2/KTX2Container.d.ts +26 -0
  420. package/dist/model/render/ktx2/KTX2Loader.d.ts +55 -0
  421. package/dist/model/render/meshes/MeshNode.d.ts +13 -0
  422. package/dist/model/render/meshes/NovaMeshWebGLDevice.d.ts +27 -0
  423. package/dist/model/render/meshes/geometry.d.ts +7 -0
  424. package/dist/model/render/meshes/mesh.d.ts +3 -0
  425. package/dist/model/render/meshes/mesh.types.d.ts +116 -0
  426. package/dist/model/render/meshes/nova-mesh-registry.d.ts +55 -0
  427. package/dist/model/render/orchestration/NovaRenderOrchestrator.d.ts +25 -3
  428. package/dist/model/render/policy/nova-render-policy.d.ts +1 -1
  429. package/dist/model/render/resources/NovaGlyphAtlasManager.d.ts +2 -2
  430. package/dist/model/render/resources/NovaTextAtlasManager.d.ts +3 -3
  431. package/dist/model/render/resources/NovaTextLayoutEngine.d.ts +1 -1
  432. package/dist/model/render/resources/nova-bitmap-upload.d.ts +10 -0
  433. package/dist/model/render/schema/NovaRenderContext.d.ts +6 -4
  434. package/dist/model/render/schema/nova-style-compiler.d.ts +5 -2
  435. package/dist/model/render/targets/NovaNodeRenderTextureSource.d.ts +29 -0
  436. package/dist/model/render/targets/NovaRenderTargetManager.d.ts +1 -1
  437. package/dist/model/render/targets/NovaRenderTexture.d.ts +57 -0
  438. package/dist/model/render/targets/nova-render-target-refs.d.ts +5 -0
  439. package/dist/model/render/targets/nova-render-target-resource.d.ts +1 -1
  440. package/dist/model/render/targets/nova-render-texture-runtime.d.ts +71 -0
  441. package/dist/model/render/textures/nova-compressed-image.d.ts +20 -0
  442. package/dist/model/render/utils/nova-icon-rendering.d.ts +3 -1
  443. package/dist/model/render/utils/nova-image-geometry.d.ts +11 -0
  444. package/dist/model/render/utils/nova-markdown-layout.d.ts +19 -0
  445. package/dist/model/render/utils/nova-text-paint.d.ts +26 -0
  446. package/dist/model/render/utils/nova-wrapped-text-layout.d.ts +19 -0
  447. package/dist/model/runtime/app/Nova.d.ts +35 -35
  448. package/dist/model/runtime/app/NovaApp.d.ts +58 -30
  449. package/dist/model/runtime/app/NovaRaphRuntime.d.ts +2 -2
  450. package/dist/model/runtime/app/createNovaRaphRuntime.d.ts +3 -3
  451. package/dist/model/runtime/assets/NovaAssetRegistry.d.ts +89 -2
  452. package/dist/model/runtime/assets/NovaVideoTexture.d.ts +38 -0
  453. package/dist/model/runtime/assets/nova-render-texture-image-identity.d.ts +4 -0
  454. package/dist/model/runtime/commands/NovaCommandBus.d.ts +1 -1
  455. package/dist/model/runtime/components/NovaComponentNode.d.ts +6 -6
  456. package/dist/model/runtime/components/NovaComponentRegistry.d.ts +1 -1
  457. package/dist/model/runtime/components/NovaSchemaRegistry.d.ts +7 -6
  458. package/dist/model/runtime/components/nova-component-metadata.d.ts +1 -1
  459. package/dist/model/runtime/components/nova-component.decorator.d.ts +2 -2
  460. package/dist/model/runtime/components/nova-defined-component.d.ts +3 -3
  461. package/dist/model/runtime/context/nova-context.d.ts +1 -1
  462. package/dist/model/runtime/cursor/NovaCursorManager.d.ts +3 -3
  463. package/dist/model/runtime/diagnostics/NovaDiagnostics_Module.d.ts +3 -3
  464. package/dist/model/runtime/interaction/NovaEvents.d.ts +16 -6
  465. package/dist/model/runtime/interaction/NovaHitIndex.d.ts +1 -1
  466. package/dist/model/runtime/interaction/NovaSpatialIndex.d.ts +2 -2
  467. package/dist/model/runtime/scene/NovaScene.d.ts +3 -3
  468. package/dist/model/runtime/scene/nova-scene-components.d.ts +6 -6
  469. package/dist/model/runtime/state/nova-store-decorators.d.ts +1 -1
  470. package/dist/model/runtime/state/nova-store-runtime.d.ts +1 -1
  471. package/dist/model/runtime/state/nova-store-tracking.d.ts +7 -3
  472. package/dist/model/runtime/sync/NovaSyncScope.d.ts +11 -2
  473. package/dist/model/runtime/sync/nova-sync-context.d.ts +2 -2
  474. package/dist/model/runtime/sync/nova-sync-ports.d.ts +2 -2
  475. package/dist/model/runtime/sync/nova-sync.types.d.ts +15 -3
  476. package/dist/model/runtime/template/NovaTemplateRuntime.d.ts +6 -6
  477. package/dist/model/runtime/tree/NovaContainer.d.ts +4 -4
  478. package/dist/model/runtime/tree/NovaNode.d.ts +58 -18
  479. package/dist/model/runtime/tree/NovaRaphNode.d.ts +8 -2
  480. package/dist/model/runtime/tree/NovaSurface.d.ts +32 -10
  481. package/dist/model/runtime/tree/nova-node-capture-invalidation.d.ts +11 -0
  482. package/dist/model/semantic/NovaSemanticService.d.ts +1 -1
  483. package/dist/model/semantic/browser/createAccessibilityBridge.d.ts +29 -0
  484. package/dist/model/sound/NovaSoundEngine.d.ts +3 -2
  485. package/dist/model/text-selection/NovaTextSelectionService.d.ts +2 -2
  486. package/dist/model/text-selection/index.d.ts +2 -2
  487. package/dist/model/text-selection/nova-text-selection.types.d.ts +1 -1
  488. package/dist/model/theme/NovaGlobalThemeRegistry.d.ts +2 -2
  489. package/dist/model/theme/NovaThemeService.d.ts +5 -3
  490. package/dist/model/theme/createTokenTheme.d.ts +15 -0
  491. package/dist/model/tools/transform-tools.d.ts +43 -0
  492. package/dist/nodes--Ds4IS2h.js +621 -0
  493. package/dist/nova-color-parser-BCN_rFRN.js +250 -0
  494. package/dist/nova-compressed-image-CE2Ya9Xa.js +46 -0
  495. package/dist/nova-mesh-registry-B7Xz5mhU.js +24 -0
  496. package/dist/nova-render-texture-image-identity-DQ09XFKs.js +15 -0
  497. package/dist/nova-text-paint-CcntsRjI.js +48 -0
  498. package/dist/tokens.d.ts +2 -0
  499. package/dist/tokens.js +50 -0
  500. package/dist/vec4-BTNv1fUp.js +20 -0
  501. package/package.json +229 -4
package/README.md CHANGED
@@ -18,15 +18,219 @@ Nova is an independent canvas rendering runtime and the foundation of the Nova e
18
18
  12. [Exported function recipes](#exported-function-recipes)
19
19
  13. [Low-level class map](#low-level-class-map)
20
20
  14. [Advanced class method index](#advanced-class-method-index)
21
+ 15. [Independent 3D runtime](#independent-3d-runtime)
21
22
 
22
23
  The companion [compiler](../@nova-js-compiler/README.md) compiles `.nova` files; the [UI Kit](../@nova-js-ui-kit/README.md) adds ready-made canvas controls. Both build on this package.
23
24
 
25
+ ## 2D lighting (experimental)
26
+
27
+ Implemented locally in dev.225; package publication is a separate step.
28
+
29
+ `@nova-lab/core/2d/lighting` adds explicit directional, point and spot sources,
30
+ convex height-aware shadow casters, alpha height receivers, lighting groups and
31
+ per-source soft shadows. Its WebGL2 compositor can shade an image or apply a
32
+ bounded pass to an existing Canvas2D scene. It creates no frame loop and does
33
+ not change the root retained renderer or Nova3D resource ownership.
34
+
35
+ ```ts
36
+ import { createLighting2D } from '@nova-lab/core/2d/lighting'
37
+
38
+ const lighting = createLighting2D({ ambient: [1, 1, 1], maxTextureSize: 1024 })
39
+ const fire = lighting.createPointLight({
40
+ position: [160, 120, 55], color: '#ffbd79', intensity: 2.4,
41
+ range: 230, sourceRadius: 12, shadows: { enabled: true },
42
+ })
43
+ // In the existing scene render callback, after drawing its artwork:
44
+ lighting.apply(context2D, { bounds: { x: 0, y: 0, width: 640, height: 360 } })
45
+ fire.set({ intensity: 2.3 })
46
+ // Scene unmount:
47
+ lighting.dispose()
48
+ ```
49
+
50
+ [API, geometry, budgets and limitations](docs/lighting-2d.md). Ocean Scene4
51
+ uses this API for its campfire. Exact sprite silhouettes, automatic node wiring,
52
+ normal-map materials and performance certification are outside the first subset.
53
+
54
+ ## Independent 3D runtime
55
+
56
+ `@nova-lab/core/3d` provides a separate spatial scene and WebGL2 renderer. It
57
+ owns its app, canvas and resources; Raph owns frame scheduling. Root and `/2d`
58
+ keep their 2D exports. Importing 3D creates no app, canvas, device, timer or worker.
59
+
60
+ ```ts
61
+ import { boxGeometry, createApp } from '@nova-lab/core/3d'
62
+
63
+ const app = createApp({ target: canvas })
64
+ const scene = app.createScene()
65
+ const camera = scene.createPerspectiveCamera({
66
+ fov: Math.PI / 3, near: 0.1, far: 100, position: [0, 0, 5],
67
+ })
68
+ const geometry = app.createGeometry(boxGeometry())
69
+ const material = app.createMaterial({ type: 'basic', color: [1, 0, 0, 1] })
70
+ scene.createMesh({ geometry, material })
71
+ app.setView({ scene, camera })
72
+ app.renderOnce()
73
+ // Dispose when the host view unmounts.
74
+ app.destroy()
75
+ ```
76
+
77
+ Coordinates are right-handed, distances use metres, angles use radians, and
78
+ camera forward is local −Z with +Y up. Geometry/material/texture references
79
+ belong to the same app. Destroy live users before destroying a shared resource;
80
+ `app.destroy()` disposes all app-owned state. Basic/PBR factors and HDR work in
81
+ linear colour and are encoded to sRGB exactly once per frame. Frames without
82
+ blended materials or effects write straight to the canvas from the material
83
+ shader, including PBR tone mapping; other frames render into a linear target and
84
+ finish with one display pass. Renderer limits and addon budgets refuse unsupported allocations explicitly.
85
+
86
+ | Optional endpoint | Purpose | Additional peers |
87
+ | --- | --- | --- |
88
+ | `/3d/controls` | Orbit, transform gizmo and snapping | none |
89
+ | `/3d/helpers` | Debug line helpers: axes, grid, bounds, camera frustum, lights (experimental) | none |
90
+ | `/3d/gltf` | Bounded glTF/GLB loading, shared assets and independent models | none; decoder adapters are explicit |
91
+ | `/3d/animation` | Clips, independent poses, manual seek and Raph playback | none |
92
+ | `/3d/effects` | Ordered HDR bloom and final display/FXAA | none |
93
+ | `/3d/documents` | Versioned logical snapshots and guarded scene projection | `@typedworks/schema` dev.56, `@typedworks/json` dev.7 |
94
+ | `/3d/commands` | Document commands, gesture preview and one supplied History | document peers, `@typedworks/commands` dev.14 and `@typedworks/history` dev.16 or compatible manifest versions |
95
+
96
+ Optional implementations and their peers are absent from the base `/3d` graph.
97
+ Install matching local archives for unpublished dev peers; source availability
98
+ does not imply an npm release. The document format starts at v1 and persists
99
+ nodes, geometry, RGBA8 textures, basic/PBR materials, cameras, lights and asset
100
+ references. It excludes playback poses, gesture preview, instances, LOD,
101
+ environment and effects. Unknown versions are refused; legacy conversion is
102
+ not provided. Edit document-owned state through its document/command binding.
103
+ Projections borrow resolver assets and own their model instances. Bindings use
104
+ the caller's Commands scope and History, and do not dispose either owner.
105
+
106
+ Shared 2D/3D canvases, arbitrary GLSL materials and a full Raphy renderer are
107
+ outside this API. Functional validation, browser coverage, memory and comparative
108
+ performance are separate acceptance scopes.
109
+
110
+ ### Rapier physics (experimental)
111
+
112
+ `@nova-lab/core/3d/physics/rapier` implements the existing physics backend
113
+ contract. Install the optional peer only when using this backend:
114
+
115
+ ```sh
116
+ pnpm add @dimforge/rapier3d-compat@0.21.0
117
+ ```
118
+
119
+ ```ts
120
+ import { createPhysicsWorld } from '@nova-lab/core/3d/physics'
121
+ import { createRapierBackend } from '@nova-lab/core/3d/physics/rapier'
122
+
123
+ // scene and boxNode belong to the application's existing 3D scene.
124
+ const backend = await createRapierBackend()
125
+ const physics = createPhysicsWorld(scene, {
126
+ backend, fixedStep: 1 / 60, maxSubSteps: 4, clock: 'app', debug: true,
127
+ })
128
+ const body = physics.createBody(boxNode, {
129
+ type: 'dynamic', shape: { type: 'box', halfExtents: [0.5, 0.5, 0.5] }, mass: 2,
130
+ })
131
+ body.applyImpulse([0, 4, 0])
132
+ // physics.destroy() releases the world; scene lifecycle also owns cleanup.
133
+ ```
134
+
135
+ The factory loads and initializes WASM; importing the entry does not require
136
+ Rapier to be installed. Root, `/3d` and `/3d/physics` do not import this adapter.
137
+ The backend creates no frame loop, timer or worker. For recorded scenarios use
138
+ `clock: 'manual'`, supply the same input before each `physics.update(1 / 60)`,
139
+ and keep the Rapier version and call order fixed.
140
+
141
+ Sphere, box, capsule, cylinder, convex hull, compound, static plane/trimesh,
142
+ fixed/ball/hinge/slider joints, motors, 32-bit filters, sensors, contacts and
143
+ raycast are supported. Distance joints are rejected because the lower radial
144
+ limit cannot be honored. `ccd` defaults to true and `maxContactPairs` to 8192;
145
+ overflow throws after the completed physics step. Buffers and events are reused,
146
+ but temporary allocations inside Rapier/wasm-bindgen remain an open acceptance
147
+ item. The API remains experimental.
148
+
149
+ ### Experimental game components
150
+
151
+ Static-level movement lives in `@nova-lab/core/3d/character`, with collision
152
+ geometry in `/3d/collision`. Feed fixed ticks from the application's existing
153
+ clock; the controller creates no loop or scene resources.
154
+ The example assumes live imported `level` and `hero` models and `anotherGroup`.
155
+
156
+ ```ts
157
+ import { createCharacterController } from '@nova-lab/core/3d/character'
158
+ import { createOctree } from '@nova-lab/core/3d/collision'
159
+
160
+ const levelCollision = createOctree()
161
+ levelCollision.addNode(level.root)
162
+ levelCollision.build()
163
+ const controller = createCharacterController(levelCollision, {
164
+ position: [0, 1, 0], radius: 0.35, height: 1.8, stepHeight: 0.3,
165
+ })
166
+ const position: [number, number, number] = [0, 0, 0]
167
+ const input = { moveX: 0, moveZ: 0, jump: false }
168
+ const patch = { position }
169
+ function fixedTick(dt: number) {
170
+ controller.update(dt, input)
171
+ controller.getPosition(position)
172
+ hero.root.setTransform(patch)
173
+ }
174
+
175
+ const independent = hero.clone({ pose: 'current' })
176
+ const bindPose = hero.clone({ pose: 'bind', parent: anotherGroup })
177
+ ```
178
+
179
+ `getPosition` writes world-space feet coordinates into the caller's array;
180
+ use a scene-root avatar or convert to the parent's local space. Movement handles
181
+ walls, ceilings, jump edges, steps and walkable slopes on a static triangle level.
182
+ Moving platforms, rigid-body pushing and Rapier KCC are separate capabilities.
183
+ The controller reuses its work buffers; the existing scene transform API keeps
184
+ its own copying semantics.
185
+
186
+ Model clones own their bones, morph state and bound clips, sharing asset-owned
187
+ geometry, materials and textures. Current pose includes active animation values;
188
+ playing actions and their clocks are not copied. Current clones require the
189
+ original node hierarchy. Destroying either instance leaves the other usable;
190
+ destroying the asset releases both. Retargeting between rigs is separate.
191
+
24
192
  ## Install and first frame
25
193
 
26
194
  Install the package and its matching workspace/release dependencies. Nova is a browser canvas runtime; the target must be an `HTMLCanvasElement`.
27
195
 
196
+ Use `@nova-lab/core/2d` for the standalone 2D API. The existing `@nova-lab/core` import remains compatible: both entrypoints share the same implementation, classes and registries. Importing either entrypoint does not create an app or browser resources.
197
+
198
+ ### Optional TypedWorks token theme
199
+
200
+ `@nova-lab/core/tokens` requires separately installed compatible `@typedworks/token`
201
+ and `@typedworks/color`. These optional peers are absent from the root/2D runtime
202
+ graph. Install exact local archives while their versions are unpublished;
203
+ workspace readiness does not imply an npm release.
204
+
28
205
  ```ts
29
- import { Nova, NovaNode, RendererType } from '@nova-lab/core'
206
+ import { createTokenTheme } from '@nova-lab/core/tokens'
207
+ import { defineTokens, defineTokenSet, token } from '@typedworks/token'
208
+
209
+ const catalog = defineTokens({ ink: token.color() })
210
+ const light = defineTokenSet(catalog, {
211
+ id: 'light',
212
+ values: { ink: { colorSpace: 'srgb', components: [0.1, 0.2, 0.3] } },
213
+ })
214
+ const dark = defineTokenSet(catalog, {
215
+ id: 'dark', extends: light,
216
+ values: { ink: { colorSpace: 'oklch', components: [0.9, 0.02, 240] } },
217
+ })
218
+ // `app` is the host's Nova application.
219
+ const theme = createTokenTheme(app, { catalog, set: light })
220
+ theme.color(catalog.tokens.ink) // Prepared #RRGGBBAA; no conversion per read.
221
+ theme.use(dark) // Updates app.theme, the only active-theme owner.
222
+ // Use the existing app.theme.observe(node) to redraw dependent nodes.
223
+ ```
224
+
225
+ The adapter resolves inherited sets/references, then clips and rounds colors to
226
+ sRGB RGBA8 at the rendering boundary. It supports color handles. Foreign handles,
227
+ theme/set ID collisions and an active legacy theme without a prepared binding
228
+ throw explicitly. The usual Nova string-color parser is unchanged.
229
+
230
+ ### First frame
231
+
232
+ ```ts
233
+ import { Nova, NovaNode, RendererType } from '@nova-lab/core/2d'
30
234
 
31
235
  const canvas = document.querySelector<HTMLCanvasElement>('#scene')!
32
236
  const app = Nova.createApp({
@@ -54,14 +258,14 @@ class WelcomeNode extends NovaNode {
54
258
  }
55
259
 
56
260
  const surface = app.createSurface('main')
57
- surface.add(new WelcomeNode(app, surface))
261
+ surface.createNode(WelcomeNode)
58
262
  app.raph.run()
59
263
 
60
264
  // On host teardown:
61
265
  app.destroy()
62
266
  ```
63
267
 
64
- `app.raph.run()` processes scheduled work for the initial frame when `scheduler.loop` is false. `app.startLoop()` and `app.stopLoop()` control a continuous loop. Motion can acquire the loop while playing. The `releaseTargetOnDestroy` option defaults to `false`, so a host-owned canvas remains usable after app teardown; setting it to `true` releases its drawing buffer/context and makes that canvas unsuitable for reuse.
268
+ `app.raph.run()` processes scheduled work for the initial frame when `scheduler.loop` is false. The loop is optional and disabled by default. `scheduler: { loop: true }`, `app.startLoop()`, or `app.options({ loop: true })` enable continuous scheduling and replay of the prepared scene on every frame. Clean frames skip scene update, matrix, render preparation, and recompilation; only frame bookkeeping and backend replay run. `app.stopLoop()` or `app.options({ loop: false })` return to rendering on changes. Motion can acquire a scheduler lease while playing without enabling unconditional replay; stopping the app loop does not release Motion's lease. Diagnostics `runtime.fps` counts completed Nova draw passes, not browser callbacks or GPU presentation. The `releaseTargetOnDestroy` option defaults to `false`, so a host-owned canvas remains usable after app teardown; setting it to `true` releases its drawing buffer/context and makes that canvas unsuitable for reuse.
65
269
 
66
270
  ### App creation options
67
271
 
@@ -108,7 +312,7 @@ app.surfaces; app.rendererConfig; app.mainRendererType
108
312
  | Hit test mode | `app.setHitTestMode('spatial')` | Chooses `linear` or `spatial` interactive indexing. |
109
313
  | Explicit DOM dispatch | `app.handleEvent('click', mouseEvent)` | Feeds a native event into Nova; usually DOM listeners do this. |
110
314
  | Cursor | `app.cursor('crosshair')` | Updates the canvas cursor. |
111
- | Loop | `app.startLoop(); app.stopLoop()` | Controls continuous scheduling. |
315
+ | Loop | `app.startLoop(); app.stopLoop()` | Controls opt-in continuous scheduling and prepared-frame replay; disabled by default. |
112
316
  | Surface | `app.createSurface('overlay')` / `app.removeSurface(surface)` | Adds/removes a logical compositing boundary. |
113
317
  | Scene | `app.createScene(MyScene)` | Constructs and mounts a `NovaScene`. |
114
318
  | Teardown | `app.destroy()` | Removes listeners, surfaces and owned resources. |
@@ -122,7 +326,7 @@ app.surfaces; app.rendererConfig; app.mainRendererType
122
326
  ```ts
123
327
  import { NovaContainer, NovaNode } from '@nova-lab/core'
124
328
 
125
- const group = surface.add(new NovaContainer(app, surface))
329
+ const group = surface.createNode(NovaContainer)
126
330
  group.setPosition(100, 80)
127
331
  group.setScale(1.5, 1.5)
128
332
  group.add(new WelcomeNode(app, surface))
@@ -154,8 +358,18 @@ node.addDisposer(() => subscription.unsubscribe())
154
358
 
155
359
  `NovaRenderPolicyInput` supports `group: 'auto' | 'always' | 'never'`, `cache: 'auto' | 'texture' | 'none'`, `textQuality: 'auto' | 'crisp' | 'performance'`, `updateMode: 'static' | 'dynamic' | 'stream'`, `topologyInvariant`, and `layer`. Use `node.configureRenderPolicy({...})`; request a cache or group only where the content actually benefits. `DEFAULT_NOVA_RENDER_POLICY` and `DEFAULT_NOVA_RENDERER_CONFIG` are exported defaults. The renderer config splits into `batching`, `text` (quality, modes, interaction, LOD, glyph/SDF and raster budget), `cache` and `diagnostics`.
156
360
 
361
+ Canvas 2D caches a surface bitmap only when `surface.renderPolicy.cache` is explicitly `texture`. The cached bitmap is reused while its retained frame remains unchanged; resizing and destruction release it. Use separate surfaces for frequently changing overlays and static chart content. WebGL keeps its existing surface cache policy.
362
+
157
363
  ## Drawing primitives and batches
158
364
 
365
+ `app.onFrameSubmitted(listener)` returns an unsubscribe function and reports
366
+ `id`, `startedAt`, `finishedAt` and `durationMs` after renderer submission.
367
+ It does not confirm compositor presentation or a physical display timestamp.
368
+ Listeners are released when the app is destroyed. `exportImage` supports PNG,
369
+ JPEG and WebP and replays the current frame before copying the WebGL canvas.
370
+
371
+ A polygon schema item accepts `closed: false` for an open contour on both Canvas 2D and WebGL. The default remains a closed polygon; Core owns stroking and retained payload snapshots.
372
+
159
373
  A `NovaNode.render()` hook draws through `this.renderer`. The schema recorder and direct methods reach the same pipeline. All coordinates are logical canvas/world coordinates under the node transform.
160
374
 
161
375
  ```ts
@@ -217,11 +431,21 @@ For batch-specific column formats, see `NovaRectBatch`, `NovaBorderBatch`, `Nova
217
431
 
218
432
  ## Text rendering and typography
219
433
 
434
+ String ellipsis in Canvas2D and WebGL uses the same segmentation boundaries and
435
+ the existing `...` marker. With native `Intl.Segmenter`, truncation preserves
436
+ whole graphemes (emoji sequences, flags and combining marks). A marker that fits
437
+ alone may be returned; if it is too wide, drawing uses an empty string. Fitting
438
+ text stays unchanged. Input and drawing share one lazily created native segmenter.
439
+ The legacy fallback without `Intl.Segmenter` preserves code points and surrogate
440
+ pairs, but does not implement full grapheme segmentation. This is separate from
441
+ multiline layout, bidi caret geometry and font-loading acceptance.
442
+
220
443
  `renderer.text` draws one `NovaText` item; `renderer.texts` submits a retained `NovaTextBatch` for dense labels. A text item needs `text` and a box (`x`, `y`, `width`, `height`). `rotation` is optional. `clip: true` clips to the item box; `clip: { x, y, width, height }` uses an explicit rectangle. Like other schema items, text also accepts `active` and `semantic`.
221
444
 
222
445
  | `NovaText` field | Values and effect |
223
446
  | --- | --- |
224
447
  | `styles.font` | `family`, pixel `size`, `style: 'normal' | 'italic'` and CSS-like `weight` from `100` through `900` or named weights. Defaults are sans-serif, 12px, normal. |
448
+ | `styles.direction` | Optional `ltr` or `rtl` base direction for a whole native text run. Omitted preserves the existing context behavior. |
225
449
  | `styles.color` / `opacity` | Text color and alpha. |
226
450
  | `styles.lineHeight` | Line height in logical pixels; defaults to font size. |
227
451
  | `styles.padding` | `{ all }`, `{ horizontal, vertical }` or per-side values. |
@@ -233,6 +457,12 @@ For batch-specific column formats, see `NovaRectBatch`, `NovaBorderBatch`, `Nova
233
457
 
234
458
  `markdown` and italic text take a run-atlas path in WebGL; glyph-atlas is not a universal fallback for complex shaping. Check both backends with the actual script and font you ship. The layout/measure helpers operate on text boxes and fonts; they do not implement a browser DOM text engine.
235
459
 
460
+ Explicit `styles.direction` is applied to native measurement and drawing, including WebGL run-atlas and oversized run tiles. Alignment stays physical: `left`, `center`, `right` and the existing overflow rule do not become logical start/end. Explicit RTL in glyph-atlas/MSDF uses the existing whole-run fallback, including Latin-only strings. Changing explicit direction produces a distinct existing text-cache entry; clean replay reuses that entry. Omitting direction preserves legacy Canvas context inheritance and the existing service-canvas defaults, so ambient DOM direction parity is not promised.
461
+
462
+ This is a display-only contract. It does not reorder multiple styled Markdown runs, add visual bidi caret/selection geometry, change hidden input-proxy ownership or enable explicit RTL SVG imports. It uses browser native shaping; it is not a new shaping engine. `NovaTextBatch` has no new flat direction property.
463
+
464
+ Markdown drawing and measurement share the same styled-run parser across Canvas2D, WebGL, the retained recorder and the standalone text layout helper. LF, CR and CRLF preserve logical lines, including trailing empty lines. Adjacent runs with the same font merge before native shaping. WebGL uses its run atlas for this subset; changing between plain text and Markdown cannot reuse the other parser's texture. Canvas2D applies Markdown opacity as it does for plain text. Markdown currently starts at the padded top-left; nested formatting, automatic wrapping, ellipsis, block alignment and styled bidi ordering are outside this subset. Existing backend font defaults and padding/rounding conventions remain separate.
465
+
236
466
  ```ts
237
467
  import type { NovaRenderer } from '@nova-lab/core'
238
468
 
@@ -261,6 +491,29 @@ function drawLabels(renderer: NovaRenderer): void {
261
491
 
262
492
  Use `app.configureRenderer({ text: ... })` for the app's text pipeline. `quality` is `performance | balanced | quality`. `mode` is a default, while `modes.timeScale`, `taskLabels` and `uiLabels` select paths by role. `interaction` controls quality and raster work while moving; `lod` limits tiny or excessive labels; `glyphs` and `sdf` configure glyph caches and SDF/MSDF. Other text fields include atlas memory budgets, zoom buckets, prewarming, raster budgets, scale bounds and fallback behavior. `NovaRendererConfigInput` accepts partial nested values, so set only the fields you need.
263
493
 
494
+ Runtime configuration applies at the next root pass. Equal normalized values keep
495
+ the existing config and schedule no frame. Text/interaction policies replay the
496
+ retained scene; batching changes also recompile existing surfaces against the
497
+ app-owned config. Updating interaction keeps warm programs and geometry. Changes
498
+ to cached raster representation use a conservative resource reset. Changes made
499
+ while the context is lost apply when its resources are recreated.
500
+
501
+ `cache.maxTextureMemoryMB` controls source-image LRU (default256MB; the old
502
+ backend used a fixed128MB regardless of this setting). Zero uses transient source
503
+ textures. Render-target attachments retain their pass owner and remain
504
+ outside source eviction and broad asset-cache resets. Source textures still
505
+ reload on those resets; existing target attachments are preserved. `cache.maxPathGeometryMemoryMB:0` uses transient path
506
+ geometry. Atlas budget aliases `cache.maxTextAtlasMemoryMB/maxGlyphAtlasMemoryMB`
507
+ normalize to `text.maxAtlasMemoryMB/maxGlyphAtlasMemoryMB`; explicit text values
508
+ win if both are provided. A prebuilt MSDF texture counts once and belongs to the
509
+ glyph pool. Atlas budgets retain their1MB floor and protect the active working
510
+ pages; an indivisible or pinned page may exceed the configured cache budget.
511
+ These limits are not a total GPU-memory cap. NaN, infinity and negative resource
512
+ budgets are rejected before updating the app configuration.
513
+
514
+
515
+ `renderer.config.cache.geometryWarmIdleMs` opts into keeping recently hidden WebGL circle and solid schema batches warm. It defaults to `0` (disabled). `maxGeometryWarmMemoryMB` defaults to 128 MiB and bounds inactive warm CPU vertex arrays plus GPU buffer capacity. Recently used inactive batches are evicted in order of last use or after the idle deadline; the last root pass stays protected. These fields are finite nonnegative numbers; setting either to zero disables warming. This budget is additional inactive storage, not a limit on active scene memory. Canvas2D and other stream caches retain their existing behavior. For example, `{ cache: { geometryWarmIdleMs: 15_000, maxGeometryWarmMemoryMB: 128 } }` improves short zoom return trips; evicted geometry still needs preparation and upload.
516
+
264
517
  | Text config group | Fields |
265
518
  | --- | --- |
266
519
  | Global path | `quality`, `mode` and `modes.timeScale` / `taskLabels` / `uiLabels`. An item can request its own `meta.textMode`. |
@@ -308,6 +561,29 @@ renderer.texts({
308
561
  })
309
562
  ```
310
563
 
564
+ ### Owned rectangle payload updates
565
+
566
+ `createRectBatch` owns a fixed number of mutable rectangle rows and publishes detached snapshots. Keep the existing `onChange: () => node.invalidate({ render: true })` for hooks that also derive bounds, children, layout, picking or other render output.
567
+
568
+ For a node that already recorded the same owned buffer, `node.invalidateRectBatch(batch)` explicitly promises that only this buffer's payload changed:
569
+
570
+ ```ts
571
+ class RectLayer extends NovaNode<MyEvents> {
572
+ readonly batch = createRectBatch({
573
+ count: 100,
574
+ onChange: () => this.invalidateRectBatch(this.batch),
575
+ })
576
+
577
+ override render(): void {
578
+ this.renderer.rects(this.batch)
579
+ }
580
+ }
581
+ ```
582
+
583
+ Eligible WebGL frames with culling off and complete owned rectangle output update the existing command, item and handle metadata without calling the node's render hook. Captures coalesce until prepare. Clip, mask, composition/effects, render targets, bounds culling, mixed output, structural work, source/count changes and unsupported transform combinations use the ordinary compile path. Canvas2D also keeps the ordinary compile path.
584
+
585
+ Node bounds, hit testing, semantics, layout and children remain caller-owned; update them through the existing APIs and ordinary invalidation. Every reader of one buffer in the same surface receives the same prepared snapshot; a mixed/scoped reader makes that update structural. Other surfaces/apps need their own invalidation. Old snapshots remain detached, and failed replay restores command metadata while forcing both GPU payload columns to reload before old/latest replay. This API does not change draw-call or upload-range policies.
586
+
311
587
  ### Font assets and measurement
312
588
 
313
589
  Register a font descriptor, then use the same family name in `styles.font`. `resolve` starts materialization and returns a `ready` flag, not a Promise. Browser `FontFace` loading is asynchronous where available; the app invalidates rendering after it loads. Render-text `NovaTextLayoutEngine.measure(text, scale)` and `renderer.measureText(text)` measure text for rendering. They are different from `NovaInputTextLayoutEngine`, which returns caret and selection geometry for editable controls.
@@ -384,6 +660,8 @@ console.log(edit.getState())
384
660
 
385
661
  The input layout accepts `text`, box size, `multiline`, `wrap`, `align`, `scrollX/Y`, font family/size/weight/style, `lineHeight`, `tabSize`, `charWidth`, padding and an optional `measureText` callback. Use the returned lines/glyphs and `coordinateToIndex`, `caretRect` and `selectionRects` to draw caret and highlight geometry.
386
662
 
663
+ Multiline input accepts LF, CR and CRLF without rewriting the document or its UTF-16 offsets. CRLF is one line break, including without `Intl.Segmenter`. Carets preserve empty and trailing lines; selection rectangles use each visual line's own endpoints when wrapping gives adjacent lines a shared index. Complex bidirectional caret placement still needs a separate shaping contract.
664
+
387
665
  ### Validation, DOM proxy, clipboard and caret
388
666
 
389
667
  Validation is independent of editing. `validate(value, context)` can await a sync or async validator; a later validation supersedes an earlier result. `markDirty`, `markTouched` and `markSubmitted` record UI state; `setResult` overrides the current result; `reset` clears it. A result is `true`, an error string or `{ message, code }`.
@@ -464,6 +742,8 @@ selection.configure(false)
464
742
 
465
743
  ## Input, events and hit testing
466
744
 
745
+ Mouse moves coalesce independently for each `pointerId`. Releasing a pointer delivers its pending last move before drag end, even when the gesture finishes before the next animation frame. A new press discards stale pre-press hover movement. Reset/destroy cancels the input owner's pending animation frame; pending events are never replayed into a new scene. The default mouse event mode retains the existing DOM listeners and node callback names.
746
+
467
747
  Canvas input is opt-in by configuration. Mark a node interactive and give it bounds (or a custom hit-test), then attach handlers.
468
748
 
469
749
  ```ts
@@ -479,6 +759,28 @@ node.offCapture('mousedown')
479
759
 
480
760
  `on`, `onCapture`, `off`, `offCapture` and `offAll` manage bubble/capture handlers. Native names include click, double click, context menu, mouse move/down/up, wheel, keyboard, enter/leave, focus/blur, selection and pointer capture; Nova adds hover and drag start/move/end/cancel. `NodeEventNames`, `CanvasDomEvents` and `NovaSupportedNativeEvents` are exported maps/lists. Nodes can call `focus`, `blur`, `select`, `deselect`, `focusedIn` and `selectedIn`; `capturePointer`, `releasePointerCapture` and `hasPointerCapture` manage a gesture. `node.setHitTest(({ localX, localY, bounds }) => localX >= bounds.x && localY >= bounds.y)` overrides default local-bounds testing; `node.toLocal(globalX,globalY)` converts coordinates. `app.setHitTestMode('spatial')` enables spatial candidate search for dense interactive scenes. `resolveNovaCursorValue` supports conditional cursor declarations.
481
761
 
762
+ ### Native Pointer Events
763
+
764
+ Choose the browser event source when creating the app. The default remains `mouse`.
765
+
766
+ ```ts
767
+ canvas.style.touchAction = 'none' // Редактор выбирает политику браузерных жестов.
768
+ const app = Nova.createApp({
769
+ target: canvas,
770
+ size: { width: 320, height: 180 },
771
+ input: { pointer: { events: 'pointer', capture: true } },
772
+ })
773
+ const node = app.createSurface('editor').createNode().options({ width: 100, height: 80 })
774
+ node.on('mousedown', event => {
775
+ // В этом режиме приходит исходный PointerEvent с pointerId/pressure/tilt.
776
+ if (event instanceof PointerEvent) console.log(event.pointerType, event.pressure)
777
+ })
778
+ ```
779
+
780
+ Pointer mode feeds original pointer down/move/up events into the existing mouse/drag callbacks. It does not attach compatibility mouse listeners. Touch enter/leave does not reset other contacts or create hover. With capture enabled, a hit node owns logical capture and its connected canvas uses native pointer capture for a live trusted contact; movement outside the canvas can finish the gesture. Synthetic/manual events retain logical capture without invoking platform capture. Native `pointercancel` and unexpected loss of an owned native capture cancel only that pointer, discard its pending move and emit `dragcancel`, without click or drag end. Explicit capture release does not cancel a later gesture a second time.
781
+
782
+ External input owners can call `app.events.cancelPointer(originalEvent)`. Cancellation detaches old state before callbacks, allowing a new gesture from a callback. Removing the last dragged node releases that pointer's state, capture and pending move; reset/destroy cancels all owned input work. Non-primary pointers do not synthesize click/double-click in pointer mode; the existing primary click heuristics remain. A gesture recognizer, pinch policy, predicted pen input and physical device acceptance are separate concerns. If native PointerEvent is unavailable, enabled pointer mode throws before attaching a canvas/backend. Configure `touch-action` on the caller-owned canvas to choose whether the browser may scroll or cancel a touch gesture.
783
+
482
784
  ## Components, templates, refs and scenes
483
785
 
484
786
  Nova supports class components, descriptor-based schema components, and compiled `.nova` templates.
@@ -579,12 +881,18 @@ unregister()
579
881
 
580
882
  `app.sync` is a `NovaSyncScope` for linking typed component/state ports. `createNovaSyncPort({ read, write, ... })` builds a port; `registerNode(node,{value:port})` returns cleanup; `link({from,to,schedule,bidirectional,transform,filter,equals})` returns a disposable link. Schedules are `immediate`, `microtask` and `frame`. `notify(endpoint,value?)` propagates a change. `createNovaComponentPropSyncPorts(componentNode)` creates ports from descriptor fields. Share a scope via `Nova.createApp({syncScope})` when several apps must synchronize.
581
883
 
884
+ `registerEndpoint(id, ports)` registers an owner that is independent of Nova nodes and returns idempotent cleanup. `NovaSyncParticipant` supplies ports, change subscriptions and disposal subscriptions; Core has no dependency on Charts or Timeline. A port write may return `false` to reject, or a Promise to wait for its owner's acceptance. `NovaSyncTransaction.signal` cancels a superseded or disconnected write. Propagation reads the accepted receiver value, including its constraints, before continuing; transaction paths prevent cycles. Removing an endpoint or disposing a scope aborts pending writes and cancels scheduled notifications.
885
+
582
886
  ## Assets, themes, motion and sound
583
887
 
584
888
  ### Assets
585
889
 
586
890
  `defineNovaAssets(namespace,{icons,images,fills,fonts})` creates immutable typed refs and a `records` map. Register bundles globally with `Nova.assets.global.use(bundle)` or per app with `app.assets.use(bundle)`. An app-local registry inherits the global registry; its own ref with the same ID takes precedence. Registration is lazy: `resolve` or a renderer consumer starts materialization. URL-backed images, SVGs and fonts load asynchronously and schedule a renderer update when ready. Keep a bundle registered for as long as its consumers exist, then call `unuse` on the same registry.
587
891
 
892
+ Local `app.assets.use` also updates a mounted scene that previously read or drew a missing ref. One bundle publishes its new definitions together; final `unuse` publishes its removals together. Each operation uses one app batch and at most one broad cache reset. Refcount-only changes schedule no frame. Failed resources keep an active version signal, so removing them still updates metadata readers. Unused records remain unmaterialized; their data signals disappear at final removal. Global and parent definitions propagate to live child registries in the same bundle batches. A local definition masks parent changes; its final removal reveals the current parent resource.
893
+
894
+ The optional fourth `NovaAssetRegistry` constructor argument observes readonly lifecycle batches, including `defined`. It takes precedence over the legacy second callback. Legacy listeners retain their original readiness/failure/removal events and do not receive definition events. App asset registries use the batch observer; they keep the existing Raph kernel and node-owned read subscriptions.
895
+
588
896
  ```ts
589
897
  import {
590
898
  createNovaImageAsset, createNovaLinearGradientAsset,
@@ -671,7 +979,7 @@ console.log(record?.descriptor.type, resolved?.ready, drawable, mode, nineSlice?
671
979
  app.assets.unuse(art)
672
980
  ```
673
981
 
674
- `use` is reference counted. Reusing the same bundle keeps its resources until the last matching `unuse`. An active ID cannot be replaced with a different descriptor; the registry throws before changing its count. Removing and re-adding an ID advances its generation, so an old texture key is not reused. App destruction disposes its local registry and renderer resources; the global registry has a separate lifetime. `dispose` is terminal and is normally called by the app, not by a component using `app.assets`.
982
+ `use` is reference counted. Reusing the same bundle keeps its resources until the last matching `unuse`. An active ID cannot be replaced with a different descriptor; the registry throws before changing its count. Removing and re-adding an ID advances its generation, so an old texture key is not reused. App destruction disposes its local registry and renderer resources; the global registry has a separate lifetime. `dispose` is terminal and is normally called by the app, not by a component using `app.assets`. Dispose manually created child registries when their owner ends: the parent retains its live children until disposal. Disposing a parent removes inherited definitions from descendants while preserving their local records; descendants remain usable as detached scopes. Definition notifications attempt all live child owners even if one modern observer throws; the first error is rethrown after delivery.
675
983
 
676
984
  ```ts
677
985
  import { NovaAssetRegistry, NovaAssets } from '@nova-lab/core'
@@ -685,11 +993,33 @@ isolatedAssets.dispose() // Terminal release; do not use this registry again.
685
993
 
686
994
  ### Loading and renderer limits
687
995
 
688
- The current asset/text capability is **partial** in the Nova capability matrix. Initial SVG materialization with unchanged pixel dimensions has a narrow content-only invalidation path. Other image, pattern, nine-slice and font completions, changed dimensions, remove/reuse and custom drawing use broader renderer cache invalidation and structural recompilation. An image atlas is not the active backend owner. Long-running atlas eviction and cold/warm browser text behavior remain unaccepted. Treat a `ready: false` source as pending; `resolve` does not expose an awaitable readiness promise. A failed load stays unready. Cross-origin images can taint the canvas and cause `exportImage` to fail with `tainted-canvas`.
996
+ The current asset/text capability is **partial** in the Nova capability matrix.
997
+ Initial SVG materialization with unchanged pixel dimensions and initial URL image,
998
+ pattern and nine-slice readiness can replay known retained bindings without user
999
+ render hooks or a broad cache reset. Asset reads inside an app's update/render
1000
+ hooks subscribe through existing node-owned phase observers, so a hook depending
1001
+ on readiness, source dimensions or metadata still runs when needed. Obsolete reads
1002
+ and removed nodes release these subscriptions. Reads outside hooks establish no
1003
+ automatic dependencies. App scopes stay distinct on a shared kernel and release
1004
+ their service data on destroy. Adding a local or inherited bundle notifies prior
1005
+ missing reads through this same phase bridge.
1006
+
1007
+ Fonts, changed SVG dimensions, failures, remove/reuse and direct/custom drawing
1008
+ retain conservative cache/structural fallbacks. An image atlas is not the active
1009
+ backend owner. Long-running atlas eviction and cold/warm browser text behavior
1010
+ remain unaccepted. Treat a `ready: false` source as pending; `resolve` exposes no
1011
+ awaitable readiness promise. A failed load stays unready. Cross-origin images can
1012
+ taint the canvas and cause `exportImage` to fail with `tainted-canvas`.
1013
+
1014
+ WebGL source textures and color atlases use premultiplied storage and sample it
1015
+ consistently with render targets, including image batches and sprite particles.
1016
+ An `ImageBitmap` uses a temporary Canvas2D source on upload to normalize its
1017
+ caller-selected alpha representation; replay reuses the GPU texture. Nova releases
1018
+ that temporary canvas and keeps ownership of the original bitmap with the caller.
689
1019
 
690
1020
  ### Themes
691
1021
 
692
- `app.theme` manages app-local definitions: `register`, `registerMany`, `use`, `active`, `activeDefinition`, `token`, `resolve`, `version`, `snapshot`, `createTokenResolver` and `observe(node)`. Token names begin with `--`.
1022
+ `app.theme` manages app-local definitions: `register`, `registerMany`, `has`, `use`, `active`, `activeDefinition`, `token`, `resolve`, `version`, `snapshot`, `createTokenResolver` and `observe(node)`. Token names begin with `--`.
693
1023
 
694
1024
  ```ts
695
1025
  app.theme.registerMany([
@@ -755,7 +1085,7 @@ app.semantics.focusNext()
755
1085
  node.clearSemantic()
756
1086
  ```
757
1087
 
758
- `NovaSemanticService` also supports `register`, `update`, `remove`, `clearScope`, `clearSource`, `syncSource`, `focusPrevious`, `getFocused`, `setFocused`, `clear` and `reset`. These are semantic data APIs; add the host's own accessibility bridge if DOM assistive technology must consume them.
1088
+ `NovaSemanticService` also supports `register`, `update`, `remove`, `clearScope`, `clearSource`, `syncSource`, `focusPrevious`, `getFocused`, `setFocused`, `clear` and `reset`. These semantic data APIs also feed the optional browser accessibility bridge described below.
759
1089
 
760
1090
  `app.exportImage({ format:'png'|'webp', quality?, pixelRatio?, rect?, background?, preferBlob?, includeSemanticSnapshot? })` returns dimensions, data URL or Blob, optional byte length and semantic snapshot. Catch `NovaExportError` and inspect `code` (`unsupported-format`, `tainted-canvas`, `context-lost`, `empty-canvas`). Cross-origin drawable sources can taint a canvas.
761
1091
 
@@ -1188,7 +1518,16 @@ stopTheme()
1188
1518
  console.log(tokens)
1189
1519
  ```
1190
1520
 
1191
- `NovaCanvas.getContext2D()` is for a Canvas2D owner; do not acquire a 2D context on the app's WebGL canvas. `NovaCanvas.onContextLost(callback)` and `onContextRestored(callback)` are single-slot hooks for a custom canvas/backend owner. The `NovaSyncScope` link handle's `dispose()` calls `unlink(id)`; direct `app.sync.unlink(link.id)` is equivalent. `NovaEvents.setPointerCapture(node,event)`, `markSpatialDirty(node,includeChildren)` and `removeNodeReferences(node)` are normally driven by node lifecycle and input routing. `NovaCursorManager.syncPointer(input)`, `markSpatialDirty(node,includeChildren)` and `reapplyNativeCursor()` are likewise host/input maintenance operations. `NovaNode.addChild`, `reorderChildren`, `renderOrderIndexOf` and `mountSubtree` are tree infrastructure; use `surface.add`, `container.add` and node lifecycle APIs for ordinary scenes. `NovaGlobalThemeRegistry.resetForTests()` and `NovaApp.setGlobalThemeDispose` are test/ownership hooks.
1521
+ Attached WebGL canvases track actual context loss and prevent its default disposal.
1522
+ During loss, scene/model changes remain accepted, GPU submissions stop and export
1523
+ rejects with `context-lost`. On restore, Nova rebuilds its programs, buffers,
1524
+ textures and targets, restores device state and schedules one full scene replay.
1525
+ Caller-owned sources remain owned by the caller. These lifecycle listeners are
1526
+ separate from the single-slot canvas hooks below. `app.destroy()` is idempotent;
1527
+ a late restore event does not restart it. WebGL2 and browser restoration support
1528
+ are required; restoration is an event, not a guarantee of presentation timing.
1529
+
1530
+ `NovaCanvas.getContext2D()` is for a Canvas2D owner; do not acquire a 2D context on the app's WebGL canvas. `NovaCanvas.onContextLost(callback)` and `onContextRestored(callback)` are single-slot hooks for a custom canvas/backend owner. The `NovaSyncScope` link handle's `dispose()` calls `unlink(id)`; direct `app.sync.unlink(link.id)` is equivalent. `NovaEvents.setPointerCapture(node,event)`, `markSpatialDirty(node,includeChildren)` and `removeNodeReferences(node)` are normally driven by node lifecycle and input routing. `NovaCursorManager.syncPointer(input)`, `markSpatialDirty(node,includeChildren)` and `reapplyNativeCursor()` are likewise host/input maintenance operations. `NovaNode.addChild`, `reorderChildren`, `renderOrderIndexOf` and `mountSubtree` are tree infrastructure; use `surface.createNode`, `container.add` and node lifecycle APIs for ordinary scenes. `NovaGlobalThemeRegistry.resetForTests()` and `NovaApp.setGlobalThemeDispose` are test/ownership hooks.
1192
1531
 
1193
1532
  ### Renderer and diagnostic ownership methods
1194
1533
 
@@ -1210,3 +1549,689 @@ console.log(tokens)
1210
1549
  | `GfxTelemetry` | `onSnapshot` subscribes to snapshots; `addUploadBytes`, `consumeAccBytes` and `stat` feed low-level telemetry. The app exposes shared `Telemetry` for diagnostics integrations. |
1211
1550
 
1212
1551
  For exact argument and return types of these backend-facing calls, follow the reexports in [`src/index.ts`](src/index.ts). They depend on render graph, dirty queue, cursor or diagnostic types that are meaningful only inside the corresponding integration lifecycle.
1552
+
1553
+ Versioned homogeneous `circle` schemas now retain their WebGL rounded geometry in GPU buffers. Camera pan/zoom reuses that geometry; changes require advancing `schema.contentVersion`. Mixed, clipped and unversioned schemas preserve the general path. The shader and paint order are unchanged; this does not promise a particular FPS.
1554
+
1555
+ Canvas 2D повторно использует `Path2D` для полигонов из отделённых неизменяемых
1556
+ снимков render generation. Кэш принадлежит backend и хранится по слабым ссылкам.
1557
+ Изменяемые direct payloads и внешние mutable вершины строят путь заново;
1558
+ открытость контура, отверстия и screen-space ширина сохраняют свои правила.
1559
+
1560
+ ### Managed rectangle updates
1561
+
1562
+ ```ts
1563
+ import { createRectBatch } from '@nova-lab/core/2d'
1564
+
1565
+ const batch = createRectBatch({
1566
+ count: 10_000,
1567
+ defaults: { width: 10, height: 10, color: '#0284c7' },
1568
+ onChange: () => node.invalidate({ render: true }),
1569
+ })
1570
+ // In node.render(): this.renderer.rects(batch)
1571
+ batch.set(42, { x: 120, y: 80, color: '#f97316' })
1572
+ batch.updateRange(100, { x: new Float32Array([20, 40]), y: [50, 60] })
1573
+ ```
1574
+
1575
+ The buffer copies inputs and owns revisions. Range columns must have equal lengths; invalid updates do not partially change data. `onChange` connects to the existing node owner; without it, schedule rendering explicitly. Count is fixed. Frames retain detached snapshots and share clean columns; changed columns still require a full column copy. The raw typed-array `NovaRectBatch` API remains available for lower-level control.
1576
+
1577
+ ## Immutable vector paths
1578
+
1579
+ ```ts
1580
+ import { definePath, hitTestPath } from '@nova-lab/core/2d'
1581
+
1582
+ const path = definePath(p => p
1583
+ .moveTo(10, 40)
1584
+ .bezierCurveTo(20, 0, 70, 0, 80, 40)
1585
+ .lineTo(10, 40)
1586
+ .closePath())
1587
+ const item = {
1588
+ path,
1589
+ fillRule: 'evenodd' as const,
1590
+ styles: {
1591
+ fill: '#0369a1',
1592
+ stroke: { color: '#0f172a', width: 2, lineCap: 'round' as const, dashPattern: [8, 3, 2] },
1593
+ },
1594
+ }
1595
+ // Inside a Nova node's render hook:
1596
+ this.renderer.path(item)
1597
+ // Painted picking in surface CSS coordinates; install through the node's custom hit handler.
1598
+ hitTestPath(item, { x: 30, y: 25 }, node.matrix, app.dpr)
1599
+ ```
1600
+
1601
+ Geometry data and metrics come from `@typedworks/geometry`; this adapter owns paint, matrices and backend resources. Paths are immutable and shared across retained snapshots. Fill supports nonzero/evenodd and multiple/self-intersecting contours. Stroke supports caps, joins, miter limits, continuous odd/zero dashes and world/screen units. Root and `/2d` export the same builder and metric helpers.
1602
+
1603
+ WebGL caches position-only meshes and applies paint through uniforms. `cache.maxPathGeometryMemoryMB` bounds resident upload arrays plus GPU buffers (default16; zero selects transient drawing). Clean, paint-only and translation replays can upload zero geometry. Geometry precision/complexity budgets fail explicitly. Node bounds/custom picking, ancestor clipping, full SVG documents, effect composition and comparative performance retain their separate contracts and acceptance work.
1604
+
1605
+ Retained render targets are released when the last committed surface that writes
1606
+ or samples their id retires. Cross-surface readers keep the target alive after
1607
+ its producer is removed. Failed prepare releases unowned candidate targets;
1608
+ failed cleanup retries without cancelling a committed frame. Canvas bitmap
1609
+ wrappers keep their separate surface owner. WebGL target resize allocates the
1610
+ replacement before retiring the old framebuffer and cleans provisional resources
1611
+ on allocation failure. These lifecycle bounds do not imply a measured heap/VRAM
1612
+ plateau or a total GPU memory cap.
1613
+
1614
+ SVG path-data preparation is optional:
1615
+
1616
+ ```ts
1617
+ import { parseSvgPathData } from '@nova-lab/core/2d/svg'
1618
+ import { Nova } from '@nova-lab/core/2d'
1619
+
1620
+ const path = parseSvgPathData('M10 20 h80 q20 0 20 20 t-20 20 z')
1621
+ // Reuse this immutable path in renderer.path({ path, styles }).
1622
+ void Nova
1623
+ ```
1624
+
1625
+ The endpoint reexports Geometry's parser and type without a second path registry.
1626
+ Root and `/2d` retain their exports and do not import this parser. SVG document,
1627
+ XML styles and external resources are a separate contract; this endpoint accepts
1628
+ path data. Native SVG bounding-box parity for corrected semicircles remains
1629
+ inconclusive in Chromium/WebKit; the deterministic analytic geometry is retained.
1630
+
1631
+ ### Opt-in multiline string text
1632
+
1633
+ ```ts
1634
+ node.renderer.text({
1635
+ text: 'A label with several words',
1636
+ x: 0, y: 0, width: 160, height: 80,
1637
+ styles: {
1638
+ wrap: 'word', // or 'grapheme'; omitted/'none' keeps the existing single-line API
1639
+ maxLines: 3,
1640
+ ellipsis: true,
1641
+ font: { family: 'sans-serif', size: 16 },
1642
+ lineHeight: 20,
1643
+ padding: { all: 4 },
1644
+ },
1645
+ })
1646
+ ```
1647
+
1648
+ Wrapped string measurement and drawing share whole native shaped lines, Unicode
1649
+ grapheme boundaries, padding and block alignment. Word mode breaks at ASCII
1650
+ horizontal whitespace and splits oversized words by grapheme; it does not promise
1651
+ Unicode line-breaking or hyphenation. `maxLines` is a positive safe integer; an
1652
+ explicit line limit, rather than box height, enables line clamping and ellipsis.
1653
+ Canvas2D and WebGL clip wrapped output to its content box. A single grapheme
1654
+ wider than that box stays intact and is clipped. With `Intl.Segmenter` absent,
1655
+ the existing code-point fallback applies. Wrapping uses native run rendering,
1656
+ including when a glyph mode is requested. Markdown wrapping is rejected explicitly;
1657
+ existing unwrapped Markdown and plain text retain their contracts. Wrapped layout
1658
+ is a rendering primitive and does not replace the separate text-input/caret model.
1659
+
1660
+ Wrapped WebGL text bakes opacity into its prepared run raster to preserve native
1661
+ glyph edge coverage. Changing opacity rerasterizes that wrapped run; clean replay
1662
+ reuses it. Existing unwrapped text retains its rendering path.
1663
+
1664
+ The WebGL contract uses a local native run raster. Native bitmap-font pixels can
1665
+ vary from direct global Canvas painting with a different context or origin; this
1666
+ does not change the source string, measured lines or glyph boundaries.
1667
+
1668
+ ### Managed font families
1669
+
1670
+ ```ts
1671
+ const fonts = Nova.assets.define('ui-fonts', {
1672
+ fonts: { body: Nova.assets.font({ family: 'Body', src: '/fonts/body.woff2', weight: '400' }) },
1673
+ })
1674
+ app.assets.use(fonts)
1675
+ // Read in a Nova lifecycle hook to observe readiness, replacement and removal.
1676
+ const family = app.assets.resolveFontFamily(fonts.fonts.body) ?? 'sans-serif'
1677
+ ```
1678
+
1679
+ The returned CSS family is isolated to the registry and that face generation; it
1680
+ is available after the managed FontFace is registered. Keep the asset ref in
1681
+ document data and resolve the ephemeral family for rendering. An unsupported,
1682
+ pending or failed font returns undefined. Choose the face ref for the desired
1683
+ weight/style; the helper does not aggregate separate files into a family.
1684
+ Repeated reads reuse the face, and unuse/dispose removes only its owner.
1685
+ Legacy resolve(fontRef) keeps the descriptor's public CSS family.
1686
+ Private readiness/failure updates tracked readers without a broad cache reset;
1687
+ definitions/removal retain the existing conservative fallback. Same-surface
1688
+ structural hook reuse follows the existing render policy/retention-key contract.
1689
+
1690
+ ### Node and group clips
1691
+
1692
+ ```ts
1693
+ const outline = definePath(p => p.moveTo(0, 0).lineTo(100, 0).lineTo(100, 80).closePath())
1694
+ group.setClip({ path: outline, fillRule: 'evenodd' })
1695
+ group.setClip({ x: 0, y: 0, width: 100, height: 80 })
1696
+ group.setClip(null)
1697
+ ```
1698
+
1699
+ A node clips itself and its descendants in its local coordinates. Immutable Path
1700
+ geometry, nested transforms and fill rules are shared with painted picking.
1701
+ Axis-aligned rectangular clips use the existing fast path. Rotated rectangles
1702
+ use exact path clipping. Canvas2D clips prepared contours; WebGL lazily creates a
1703
+ bounded color target and a cached geometry mask, without requiring stencil on the
1704
+ main canvas. Targets belong to the retained frame and are released when its clip
1705
+ is removed; unchanged masks reuse their raster and allocation. Group opacity,
1706
+ alpha-image masks and effect chains are separate APIs, not implied by setClip.
1707
+
1708
+ ### Isolated group composition
1709
+
1710
+ ```ts
1711
+ group.setComposition({ opacity: 0.5, blendMode: 'multiply' })
1712
+ group.setComposition({}) // explicit isolation with opacity 1 and normal blending
1713
+ group.setComposition(null)
1714
+ ```
1715
+
1716
+ Composition applies opacity once to the assembled subtree. Existing node.opacity
1717
+ keeps its previous contract. Supported modes are normal, multiply, screen,
1718
+ overlay, darken, lighten, difference and exclusion. Default bounds include visible
1719
+ descendants' declared render bounds; optional local bounds explicitly limit the
1720
+ isolated content. Draw outside declared bounds requires setLocalRenderBounds.
1721
+ Canvas2D uses a bounded offscreen canvas. WebGL reuses a bounded color target and
1722
+ captures a bounded backdrop for non-normal blending; path clips in blended frames
1723
+ also preserve their backdrop. Removing the scope releases its retained targets.
1724
+ Transforms on a surface with composition currently use structural compilation to
1725
+ recompute crop bounds. Ordinary surfaces retain the existing transform path.
1726
+
1727
+ ### Alpha image masks
1728
+
1729
+ ```ts
1730
+ const assets = Nova.assets.define('editor-masks', {
1731
+ images: { soft: Nova.assets.image('/masks/soft.png') },
1732
+ })
1733
+ app.assets.use(assets)
1734
+ group.setMask({ image: assets.images.soft, x: 0, y: 0, width: 240, height: 160 })
1735
+ group.setMask(null)
1736
+ ```
1737
+
1738
+ Mask image color is ignored; its alpha controls the isolated subtree. Coordinates
1739
+ are local to the node. Images, canvas/ImageBitmap and drawable asset refs work;
1740
+ a string means an asset id. Pending/failed/missing sources remain transparent.
1741
+ Readiness uses the existing scoped asset observer. Cached mask pixels are reused
1742
+ on replay. After changing a caller-owned canvas/image, call group.invalidateMask()
1743
+ to refresh that node's snapshot; no manual revision is required. Nova does not
1744
+ close or resize caller sources. Removal releases owned mask targets. Default
1745
+ picking checks mask bounds/readiness and existing node geometry, without reading
1746
+ image alpha pixels or synchronizing GPU readback.
1747
+
1748
+ ### Optional composition effects
1749
+
1750
+ ```ts
1751
+ import { colorMatrix } from '@nova-lab/core/2d/effects'
1752
+
1753
+ const grayscale = colorMatrix([
1754
+ 0.2126, 0.7152, 0.0722, 0, 0,
1755
+ 0.2126, 0.7152, 0.0722, 0, 0,
1756
+ 0.2126, 0.7152, 0.0722, 0, 0,
1757
+ 0, 0, 0, 1, 0,
1758
+ ])
1759
+ group.setEffects([grayscale])
1760
+ group.setEffects(null)
1761
+ ```
1762
+
1763
+ Effects isolate the subtree and run in array order before its image mask, group
1764
+ opacity and blending. The color matrix uses four row-major RGBA rows of five
1765
+ finite float32 coefficients with finite worst-case row sums. Offsets use normalized 0..1 units. It transforms
1766
+ straight RGBA, clamps each channel, then premultiplies; transparent source RGB is
1767
+ zero. Its scope is the current processing region, initially the declared composition bounds. A preceding blur can enlarge that region. Coefficients and chains are
1768
+ snapshots. Point effects do not enlarge picking bounds. Canvas reads its bounded
1769
+ pixels and requires an origin-clean source; WebGL stays on the GPU. Up to two
1770
+ bounded ping-pong targets are reused across a chain. Removing stages releases
1771
+ unused targets; the GPU processor is shared within the backend and released
1772
+ after its last retained owner. Unused scenes import no effect implementation and
1773
+ allocate no effect programs/targets.
1774
+
1775
+ ### Gaussian blur
1776
+
1777
+ ```ts
1778
+ import { blur } from '@nova-lab/core/2d/effects'
1779
+ group.setEffects([blur(2)])
1780
+ ```
1781
+
1782
+ The number is standard deviation in screen CSS pixels, after node transforms;
1783
+ the supported range is 0..64. Zero keeps isolation and performs no filter passes.
1784
+ Blur uses two separable, normalized Gaussian passes on premultiplied RGBA, truncated
1785
+ at ceil(3 * sigma * DPR) physical pixels with transparent-black extension. Each
1786
+ pass has the backend's RGBA8 storage boundary. This is Nova's declared kernel,
1787
+ not a promise of pixel equality with browser CSS/SVG blur approximations. It uses
1788
+ the existing RGBA/sRGB working space. Halo is retained outside the viewport and
1789
+ image mask until filtering finishes; clipping/masking, opacity and blending apply
1790
+ to the result. Source and up to two ping-pong attachments remain bounded by the
1791
+ visible output plus the chain's halo. GPU limits produce an explicit error.
1792
+ Kernel caches are bounded (eight CPU entries, four textures per GPU processor),
1793
+ and the GPU cache is released with its final owner. Direct sigma/DPR combinations
1794
+ requiring more than 8191 physical kernel pixels of radius are rejected. Picking
1795
+ continues to use node geometry.
1796
+
1797
+ Ordered chains keep each stage's region: alpha offsets before blur cannot fill its future halo. Ancestor composition includes visible child effect bounds. Spatial targets use local projection so offscreen source geometry can contribute to the visible blur.
1798
+
1799
+ ### Drop shadow
1800
+
1801
+ ```ts
1802
+ import { dropShadow } from '@nova-lab/core/2d/effects'
1803
+ group.setEffects([dropShadow({ x: 4, y: 6, blur: 2, color: '#0008' })])
1804
+ ```
1805
+
1806
+ Offsets and Gaussian standard deviation use screen CSS pixels. Finite offsets
1807
+ within ±4096 and blur 0..64 are supported. Colors accept normalized RGBA tuples,
1808
+ hex, comma-separated RGB(A), or black/white/red/green/blue/transparent; other
1809
+ strings fail explicitly. Options are immutable snapshots. The shadow filters
1810
+ only input alpha, colors it and composites the original input above it. A zero
1811
+ blur uses one pass; transparent shadow color uses none. Each effect preserves
1812
+ its own original input, including after color matrices or preceding shadows.
1813
+ The source and two reusable stage targets suffice for ordered chains without
1814
+ texture feedback. Removing effects releases their targets and processors.
1815
+ Canvas uses its native straight-RGBA ImageData boundary; GPU stages remain
1816
+ premultiplied RGBA8. Picking continues to use the node geometry.
1817
+
1818
+
1819
+ ### Browser accessibility bridge
1820
+
1821
+ ```ts
1822
+ import { createAccessibilityBridge } from '@nova-lab/core/2d/accessibility'
1823
+
1824
+ const bridge = createAccessibilityBridge(app, {
1825
+ target: accessibilityHost, // A host-owned HTMLElement beside the canvas.
1826
+ scope: 'editor',
1827
+ label: 'Editor controls',
1828
+ onActivate: region => documentController.activate(region.id),
1829
+ onFocusChange: region => focusIndicator.show(region?.bounds),
1830
+ })
1831
+ bridge.refresh() // After semantic-only changes without a submitted frame.
1832
+ bridge.focus('open-document')
1833
+ bridge.destroy() // Before app.destroy().
1834
+ ```
1835
+
1836
+ The adapter projects existing semantic regions to keyed native DOM controls;
1837
+ `app.semantics` remains the focus owner. Submitted frames refresh the projection.
1838
+ Labels use text content, hidden regions are excluded, and disabled controls stay
1839
+ readable. Native buttons keep browser keyboard activation. Keyboard events stop
1840
+ at the bridge to avoid a second delivery through Nova's global canvas listener.
1841
+ External inputs keep focus during refresh. The host draws visible focus feedback
1842
+ and owns domain actions and bridge teardown. One bridge may own a semantic focus
1843
+ scope. The default limit of 1000 regions rejects overflow explicitly; configure
1844
+ `maxRegions` when needed. The flat projection does not implement hierarchical
1845
+ trees/grids or replace editable text input. Importing the endpoint creates no DOM.
1846
+ Physical assistive-technology acceptance remains a separate product check.
1847
+
1848
+ ### Optional editor geometry tools
1849
+
1850
+ ```ts
1851
+ import { resizeHandlePoint, snapPointToGrid, snapPointToGuides } from '@nova-lab/core/2d/tools'
1852
+
1853
+ const handle = resizeHandlePoint(bounds, 'ne', { rotation, matrix })
1854
+ const gridPoint = snapPointToGrid(pointer, 10)
1855
+ const snapped = snapPointToGuides(pointer, [
1856
+ { axis: 'x', value: 100, id: 'left-edge' },
1857
+ { axis: 'y', value: 80, id: 'top-edge' },
1858
+ ], 4)
1859
+ ```
1860
+
1861
+ The pure endpoint also exports `rotateHandlePoint`, `resizeHandleCursor` and
1862
+ `snapResizeToGrid`. Bounds, points and Canvas-style affine matrices reuse
1863
+ TypedWorks Geometry. Handle rotation uses radians around the bounds centre,
1864
+ then applies the optional parent/view matrix. Rotation-handle offset uses bounds
1865
+ units and defaults to 28. Grid inputs, guide inputs and tolerance must share a
1866
+ coordinate frame; nearest guide ties retain input order. Editors own candidate
1867
+ selection, screen-to-world conversion, visible guides, gestures, constraints
1868
+ and history. The helpers do not import the renderer or create document state.
1869
+
1870
+
1871
+ ### Explicit bitmap sampling
1872
+
1873
+ `renderer.icon({ icon: image, x, y, width, height, styles: { sampling: 'nearest' } })`
1874
+ selects nearest-neighbour sampling. `sampling: 'linear'` selects WebGL bilinear
1875
+ filtering or native Canvas image smoothing. Canvas smoothing kernels vary by
1876
+ browser and do not promise identical pixels to GPU linear interpolation. Omitting
1877
+ sampling preserves the existing backend default. Sampling is scoped to that image;
1878
+ masks, text and subsequent draws keep their own settings. Two lazy WebGL samplers
1879
+ share the existing source texture and are released on destroy/context loss.
1880
+
1881
+
1882
+ ### Linear hit-test work
1883
+
1884
+ The default linear mode snapshots the public interactive-node Set before shape
1885
+ callbacks. It preserves callback order and chooses the final visual target after
1886
+ all callbacks, including changes to render order. Bounds reject precedes ancestor
1887
+ clip checks. Canonical retained bounds reuse avoids a copy for misses; custom
1888
+ shape callbacks still receive detached bounds. Overridden geometry queries and
1889
+ `containsPoint` keep their public paths. Clips are checked again after callbacks
1890
+ because callbacks can change an ancestor clip. This reduces linear work without
1891
+ changing the default mode or introducing an index/cache owner; dense scenes can
1892
+ still opt into the existing spatial mode explicitly.
1893
+
1894
+ ### Requested asset readiness for external render hosts
1895
+
1896
+ `await app.assets.whenReady({signal})` waits for materializations already requested
1897
+ by this registry, including isolated fonts. It rejects failed assets, cancellation
1898
+ and registry disposal. Removing a pending asset releases the wait. `pendingCount`
1899
+ reports currently loading materializations. Neither API loads unused assets or
1900
+ starts a render loop. A host should run/flush, await assets, then run/flush again;
1901
+ if that reveals more assets, repeat until pendingCount is zero. Missing asset
1902
+ definitions retain existing Nova semantics; this is not manifest validation.
1903
+ The optional Raphy bridge lives in `@nova-lab/raphy`; Core has no dependency on it.
1904
+
1905
+
1906
+ ### Optional document commands and history
1907
+
1908
+ ```ts
1909
+ import { registerDocumentCommand, bindDocumentHistory } from '@nova-lab/core/2d/commands'
1910
+
1911
+ const edit = registerDocumentCommand(app.commands, {
1912
+ scope: editorCommands, history: documentHistory,
1913
+ command: renameCommand, operation: renameOperation,
1914
+ getHistoryOptions: () => ({ coalesce: { key: 'rename', windowMs: 300 } }),
1915
+ })
1916
+ await edit.run({ id: 'shape-1', name: 'Example' })
1917
+ const history = bindDocumentHistory(app.commands, {
1918
+ scope: editorCommands, history: documentHistory, undo: undoCommand, redo: redoCommand,
1919
+ })
1920
+ await history.undo()
1921
+ history.destroy()
1922
+ edit.destroy()
1923
+ ```
1924
+
1925
+ Install compatible TypedWorks Commands and History separately for this endpoint.
1926
+ The adapter borrows the document's existing command scope and History owner.
1927
+ Only explicitly registered document IDs return Promises; existing synchronous
1928
+ NovaCommandBus handlers and frame updates retain their contract. Operations own
1929
+ model changes, inverses and view invalidation; live scene trees/caches do not
1930
+ enter history. Transactions/coalescing use the same history stack. Occupied Nova
1931
+ IDs are rejected. Destroy removes only the binding's registrations and cancels
1932
+ queued/cooperative invocations; it does not dispose borrowed owners or promise
1933
+ rollback of arbitrary external effects. Dispose bindings before the document,
1934
+ scope or app. Root and /2d import without these optional peers, and importing the
1935
+ adapter creates no scope, history, DOM or renderer resources.
1936
+
1937
+
1938
+ Registered `kind: 'schema-component'` items expand during frame compilation,
1939
+ including mixed schemas of 64 or more active items. Both backends replay the
1940
+ same builtin output in painter order; clean retained frames do not rerun the hook.
1941
+ Use `measureBounds` for custom drawing bounds and node-owned `setHitTest` /
1942
+ `addDisposer` for interaction and resources. Unknown schema types and primitive
1943
+ metadata without a supported drawing hook keep the existing skip behavior.
1944
+
1945
+
1946
+ Explicit plain text vertical alignment uses the native font anchor in WebGL.
1947
+ Run and glyph atlases preserve measured ink outside the implicit text box;
1948
+ explicit clips and inner padding apply at quad output. Independent glyphs are
1949
+ used only when native run and pair advances agree; other shaping uses whole runs.
1950
+ Clean replay reuses cached measurements and rasters. Set alignment explicitly
1951
+ when matching Canvas and WebGL: their legacy omitted defaults remain different.
1952
+
1953
+
1954
+ ### SVG document data
1955
+
1956
+ ```ts
1957
+ import { importSvgDocument, exportSvgDocument, readSvgDocument } from '@nova-lab/core/2d/svg/documents'
1958
+
1959
+ const document = importSvgDocument(svgSource)
1960
+ const restored = readSvgDocument(JSON.parse(JSON.stringify(document)))
1961
+ const svg = exportSvgDocument(restored)
1962
+ ```
1963
+
1964
+ This optional endpoint imports the declared SVG subset into immutable versioned
1965
+ plain data. It preserves paths, groups, affine transforms, fills/strokes, local
1966
+ clips, plain text and inert image references; unsupported constructs fail with
1967
+ `NovaSvgError`. It creates no DOM, Nova app, renderer or network requests.
1968
+ `@nova-lab/core/2d/svg` remains the lightweight path-data parser.
1969
+ The document endpoint does not expose the private Nova SVG drawing adapter.
1970
+
1971
+ Default export and `{ strokeMode: 'native' }` preserve the data roundtrip.
1972
+ For explicit visual SVG export, use
1973
+ `exportSvgDocument(document, { strokeMode: 'outline', tolerance: 0.25 })`.
1974
+ It replaces world path strokes with one nonzero filled contour per stroke,
1975
+ keeps the original fill first and applies node opacity, transform, visibility,
1976
+ id and clip once around both paints. Curves and round caps/joins use Geometry's
1977
+ finite positive tolerance in SVG/world units before node transforms (default
1978
+ 0.25); fixed export command/element/source and Geometry segment budgets still
1979
+ apply. Stroked text and screen strokes are located atomic `unsupported` errors
1980
+ in this mode. Native/default support is unchanged. Outline export changes the
1981
+ exported model: it does not preserve editable stroke fields, and read, JSON and
1982
+ the drawing factory never enable it implicitly. No DOM or resources are created.
1983
+ This explicit geometry mode is not a claim of general browser stroke pixel
1984
+ parity; native verification of the diagnosed straight zero-dash case and curve
1985
+ quality remain separate acceptance work.
1986
+
1987
+ Exact native raster identity for rotated text is limited by browser transform
1988
+ representation even for equal matrices; the recorded strict visual gate remains
1989
+ open. Fonts, image loading and document editing belong to their real consumers.
1990
+
1991
+
1992
+ Input proxy synchronization preserves backward anchor/focus as a normalized DOM
1993
+ range with `selectionDirection: 'backward'`. Logical LTR Left/Right without Shift
1994
+ collapse an existing selection to its corresponding edge before moving further.
1995
+ Shift, word shortcuts and the existing controller/proxy ownership remain unchanged.
1996
+ This low-level contract does not imply mounted UI Kit native-input or physical IME
1997
+ acceptance; those require the consumer to connect proxy events to its controller.
1998
+
1999
+
2000
+ Schema-component recursion keeps the existing maximum depth across both returned
2001
+ schemas and synchronous `renderer.schema()` calls inside hooks. Depth is scoped
2002
+ to each renderer and restored on success or error; separate renderers and sibling
2003
+ roots remain independent. Builtin and unsupported schema paths do not allocate
2004
+ the lazy depth map. The existing mode dispatch and public error remain unchanged.
2005
+
2006
+
2007
+ Disposing a native input proxy removes its input/composition listeners before
2008
+ detaching the textarea. A retained old element cannot call back after disposal
2009
+ or a fresh attach. Detach/reattach preserves the same element and listeners;
2010
+ repeated disposal and retry after a failed append remain supported.
2011
+
2012
+
2013
+ Sound engine destruction is idempotent. Pending unlock never marks a destroyed
2014
+ engine unlocked, and automatic first-input/immediate attempts handle rejection
2015
+ while remaining retryable. Explicit unlock keeps its rejecting Promise contract.
2016
+
2017
+
2018
+ A destroyed sound engine does not retain late loaded assets. Valid load/preload
2019
+ after destruction resolves without backend work; descriptor validation and explicit
2020
+ loader rejection remain observable. Pending decoding is not automatically aborted.
2021
+
2022
+
2023
+ Group composition supports sixteen standard blend modes. New modes use a lazy
2024
+ per-renderer Canvas semantic probe; a bounded RGBA fallback handles nonconforming
2025
+ native Canvas implementations. Fallbacks expose canvasBlendFallbacks and
2026
+ canvasBlendReadbackPixels; unreadable source/backdrop fails explicitly. Existing
2027
+ modes keep their native path, and WebGL uses the shared composition shader.
2028
+
2029
+
2030
+ Effective active/visible values use owner-local scalar storage while retaining
2031
+ existing reactive signals, equality guards and inherited phase propagation. Lazy
2032
+ defaults and explicitly written undefined remain distinct; other properties keep
2033
+ their Map storage. No public state owner or hit-test ordering changes.
2034
+
2035
+ Width and height effective property values use lazy owner-local scalar storage. Public virtual reads, reactive tracking and layout semantics remain unchanged.
2036
+
2037
+ Plain string text uses top vertical alignment by default in Canvas2D and WebGL. Set styles.align.vertical to 'middle' explicitly for centered placement. Existing font defaults are unchanged.
2038
+
2039
+
2040
+ Plain text with an omitted font family uses `sans-serif` for Canvas2D drawing and measurement, matching WebGL and the retained builder. Set an explicit family to preserve a previous choice. Explicit empty/invalid values keep their prior Canvas behavior; Markdown and wrapped text retain their existing contracts. No shared style compiler or extra resource is created during drawing.
2041
+
2042
+
2043
+ WebGL text-atlas eviction removes its fallback pointer only while the pointer still
2044
+ refers to that exact evicted entry. Pointers to a newer retained scale are preserved;
2045
+ cache budgets, current-frame pinning and fallback selection retain their contract.
2046
+
2047
+
2048
+ Automatic deferred-text continuation requires actual run or glyph raster progress.
2049
+ A zero text budget leaves pending text suspended without a microtask retry loop;
2050
+ manual invalidation or a positive configured budget can resume preparation.
2051
+ Generic image uploads do not count as text progress. Scheduler ownership is unchanged.
2052
+
2053
+
2054
+ ### Partial-alpha path coverage
2055
+
2056
+ WebGL paths share maximal union strips across adjacent tessellation bands. Partial-alpha
2057
+ fill/stroke coverage uses one lazy cropped render target with per-sample stencil union;
2058
+ paint alpha is applied once. Ordinary opaque scenes allocate no union attachments.
2059
+ Warm geometry and matrix-only transforms reuse VBOs. Crop resize may allocate target
2060
+ storage; it is reported separately from VBO uploads. The scratch target follows the
2061
+ existing render-target lifecycle and idle cleanup.
2062
+
2063
+
2064
+ ### Auto text routing
2065
+
2066
+ The current auto mode selects run-atlas for direct and batched text. It no longer
2067
+ scans strings or samples batch labels to compute a decision with identical outcomes.
2068
+ Explicit glyph/MSDF modes, role overrides and complex-text fallback remain available.
2069
+
2070
+
2071
+ ### Composition coverage (1.0.0-dev.75)
2072
+
2073
+ Path clips and isolated composition preserve the active output sample count in
2074
+ backend-owned optional raster attachments. Mask and color both retain edge
2075
+ coverage; ordinary scenes and explicit public single-sample targets allocate
2076
+ no new attachments. Backdrop/effect reads use the canonical resolved texture,
2077
+ with explicit resolve/resume state and cleanup on failure, resize and destroy.
2078
+
2079
+
2080
+ ### Oversized plain text (1.0.0-dev.76)
2081
+
2082
+ WebGL keeps native whole-run shaping while rasterizing oversized plain text into
2083
+ viewport-selected atlas cells. Each physical canvas/page is bounded by the smaller
2084
+ of 1024 pixels and the current GPU texture limit, including its gutter. Cropped
2085
+ composition targets use their physical output rectangle; explicit text clips do
2086
+ not change cache identity. Existing soft atlas budgets and current-frame pinning
2087
+ remain in effect. Logical raster counters stay per run; optional
2088
+ `textRasterTileCount` reports physical oversized-cell raster operations. Markdown
2089
+ and wrapped-text raster paths retain their existing contract.
2090
+
2091
+
2092
+ Dev.77 reuses one bounded physical path-union scratch capacity across mixed path
2093
+ bounds; active crop limits clearing, resolve and sampling. Output/profile changes
2094
+ can reallocate. This reduces warm allocation/upload work, with explicit retained
2095
+ capacity cost; it does not claim a frame-time or SVG fidelity improvement.
2096
+
2097
+
2098
+ Dev.78 keeps Markdown's cached full-box raster independent of the first default
2099
+ or explicit clip. Clip is applied when drawing the quad; wrapping retains its
2100
+ intrinsic content clip. Changing clip reuses the prepared raster consistently.
2101
+
2102
+
2103
+ In `1.0.0-dev.79`, oversized Markdown and wrapped text use the existing bounded tile owner, page budgets and disposal path. Whole styled runs and final wrapped lines preserve the existing shaping semantics; ordinary text retains its single-raster path.
2104
+
2105
+ ## Optional custom primitives через builtin commands
2106
+
2107
+ `@nova-lab/core/2d/primitives` экспортирует `definePrimitive<TSchema>` и
2108
+ `NovaPrimitiveUnsupportedError`; основной root и `/2d` этот optional code не
2109
+ подключают. `definePrimitive` создаёт обычный frozen descriptor
2110
+ `kind: 'schema-component'` для `app.schema.register`. Новый registry, node,
2111
+ render opcode или GPU/resource owner не создаются. Раскрытие выполняет прежний
2112
+ schema compiler, а Canvas2D/WebGL получают существующие builtin commands.
2113
+
2114
+ ```ts
2115
+ import { definePath, getPathBounds, hitTestPath, Nova, NovaNode } from '@nova-lab/core/2d'
2116
+ import { definePrimitive } from '@nova-lab/core/2d/primitives'
2117
+
2118
+ const geometry = definePath(builder => builder
2119
+ .moveTo(0, 0).lineTo(40, 0).lineTo(0, 40).closePath())
2120
+ const paint = { path: geometry, styles: { fill: '#4264db' } }
2121
+ const Triangle = definePrimitive<{ fill?: string }>({
2122
+ type: 'example.triangle',
2123
+ name: 'Triangle',
2124
+ version: '1.0.0',
2125
+ requires: ['path'],
2126
+ renderSchema: (_context, item) => [{
2127
+ type: 'path', path: geometry,
2128
+ styles: { fill: item.props?.fill ?? '#4264db' },
2129
+ }],
2130
+ measureBounds: () => getPathBounds(geometry),
2131
+ })
2132
+ const schema = [{ type: Triangle.type, props: { fill: '#4264db' } }]
2133
+ type SceneEvents = Record<string, never>
2134
+ class TriangleNode extends NovaNode<SceneEvents> {
2135
+ override render(): void {
2136
+ this.renderer.schema(schema)
2137
+ }
2138
+ }
2139
+ const canvas = document.querySelector<HTMLCanvasElement>('#scene')!
2140
+ const app = Nova.createApp<SceneEvents>({ target: canvas, size: { width: 320, height: 180 } })
2141
+ app.schema.register(Triangle)
2142
+ const node = app.createSurface('example-primitives')
2143
+ .createNode(TriangleNode).options({ width: 40, height: 40 })
2144
+ node.setRenderBoundsFromSchema(schema)
2145
+ node.setHitTest(({ worldX, worldY }) => hitTestPath(
2146
+ paint, { x: worldX, y: worldY }, node.matrix, app.canvas.dpr,
2147
+ ))
2148
+ const repaint = () => node.invalidate({ render: true, flush: true })
2149
+ window.addEventListener('resize', repaint)
2150
+ node.addDisposer(() => window.removeEventListener('resize', repaint))
2151
+ app.raph.run()
2152
+ // При размонтировании приложение освобождает дерево и этот listener.
2153
+ const destroy = () => app.destroy()
2154
+ ```
2155
+
2156
+ Пример предполагает существующий DOM target `<canvas id="scene"></canvas>`. Immutable
2157
+ `Path` принадлежит consumer. Bounds обязаны покрывать фактический paint, включая
2158
+ stroke/overhang; при изменении geometry consumer обновляет schema, node bounds,
2159
+ hit-test данные и invalidation согласованно. `measureBounds` не вычисляется из
2160
+ произвольного hook автоматически, не исправляется и не заменяется пустым rect
2161
+ при неверном результате. Painted hit-test и cleanup принадлежат **реальной ноде**,
2162
+ а не отдельному schema item: descriptor не имеет automatic hit-test, resource
2163
+ loader, disposer или callbacks жизненного цикла. `addDisposer` освобождает только
2164
+ ресурсы, действительно принадлежащие instance; чужие shared resources не удаляются.
2165
+
2166
+ `type`, `name`, `version` — обязательные непустые строковые metadata (version не
2167
+ является package release и не разбирается новым SemVer parser). `renderSchema` и
2168
+ `measureBounds` обязательны и должны быть функциями. `requires` обязателен, может
2169
+ быть пустым, копируется и замораживается; повторы удаляются с сохранением порядка.
2170
+ Неизвестное requirement, неверные metadata или hooks дают `TypeError` при define.
2171
+ Definition не регистрируется и не вызывает hooks, DOM, сеть, scheduler или GPU.
2172
+ Оба hooks синхронные по существующему schema contract; automatic normalize не
2173
+ выполняется. Helper не вызывает hook при define для проверки его результата.
2174
+ Изменение исходного definition/массива после define не меняет descriptor.
2175
+
2176
+ `requires` принимает существующие `keyof NovaRendererCapabilities` и три optional
2177
+ groups. Для существующей capabilities object требуется явное `true` **и**
2178
+ наличие command method; `false` и отсутствующий key не обходятся методом.
2179
+ `canvas2d`/`webgl` требуют явного `true` и никогда не выводятся из методов. Это capabilities
2180
+ конкретного recorder/renderer, а не обещание типа будущего App backend: retained
2181
+ builder объявляет оба false. Поэтому `requires: ['webgl']` в обычном node.render
2182
+ не проходит через builder даже у App с WebGL output; builtin lowering обычно
2183
+ требует `path`/`rect` и нужные optional operations, а не raw backend identity.
2184
+ Только legacy renderer **без всей capabilities property**, например прежний
2185
+ `NovaRenderContext`, допускает method-based fallback для command requirements.
2186
+
2187
+ | Requirement | Требуемый метод / методы |
2188
+ | --- | --- |
2189
+ | `schema`, `rect`, `border`, `line`, `circle`, `arc`, `polygon`, `path`, `icon`, `text`, `particles`, `measureText` | Одноимённый command method |
2190
+ | `patternRects`, `rectBatches`, `stripeBatches`, `iconBatches`, `textBatches` | `patternRect`, `rects`, `stripes`, `icons`, `texts` соответственно |
2191
+ | `clipPath` | `clipPath` |
2192
+ | `composition` | `beginComposition` и `endComposition` |
2193
+ | `renderTargets` | `beginRenderTarget`, `endRenderTarget`, `drawRenderTarget` |
2194
+
2195
+ У трёх optional groups отсутствие нового capability key не мешает существующим
2196
+ builder/Canvas2D methods. Но явно объявленный соответствующий flag `false`
2197
+ запрещает группу; flag `true` не заменяет отсутствующий метод. Guard проверяет весь
2198
+ список **до пользовательского renderSchema**. При отказе бросается
2199
+ `NovaPrimitiveUnsupportedError` с `primitiveType`, `rendererId` (`unknown` у legacy
2200
+ context без id) и собственным frozen `missing` в порядке requires. Пользовательский
2201
+ hook не вызывается; сохранение committed frame и retry обеспечивает прежний compiler.
2202
+
2203
+ `renderSchema` записывает или возвращает только поддержанные builtin commands.
2204
+ `requires` описывает потребности, но не анализирует тело callback и не является
2205
+ sandbox. Raw GL/Canvas hooks, arbitrary mesh/shader, второй transform/cache owner
2206
+ и собственное управление backend resources этим API не вводятся. Обычные
2207
+ schema ordering, recursion limit, clip/composition scopes, legacy unknown/primitive
2208
+ visual skip и node disposal остаются прежними. Наличие descriptor не гарантирует
2209
+ native pixel/performance acceptance конкретного custom drawing.
2210
+
2211
+
2212
+ ### SVG drawing and plain text strokes
2213
+
2214
+ `@nova-lab/core/2d/svg/documents` remains pure document import/export.
2215
+ The optional `@nova-lab/core/2d/svg/renderer` exposes `createSvgDocumentRenderer`:
2216
+ call its `render(renderer, worldMatrix?, dpr?)` inside an existing node render hook,
2217
+ and `dispose()` when the owner is removed. Fonts and images stay caller-owned.
2218
+ Root and `/2d` do not import this adapter.
2219
+
2220
+ Plain `renderer.text` accepts independent `styles.fillOpacity` and
2221
+ `styles.stroke` (color, width, opacity, caps/joins/miter/dash in world units).
2222
+ `fillOpacity: 0` draws stroke only. Overall `styles.opacity` applies once to
2223
+ the painted run. The existing run raster path handles stroke when glyph/MSDF
2224
+ was requested. New paint options with markdown/wrap and screen-unit text strokes
2225
+ are explicitly unsupported. Native visual/performance acceptance is pending;
2226
+ the dev API does not imply full SVG/native parity.
2227
+
2228
+ ## Dev.103: prepared stroke bounds ownership
2229
+
2230
+ Prepared strokes retain contours without retaining their temporary outline Path for lazy bounds. Geometry4 `getContourBounds` preserves the bounds value and deferred overflow error. Cache keys, the eight-variant limit, tessellation, public APIs and eager sound/input behavior are unchanged. The accepted isolated memory comparison reduced the source-bound command category; the full 2 MiB post-destroy memory gate remains open.
2231
+
2232
+ ## 2D + 3D example
2233
+
2234
+ [Courier](./examples/courier/README.md) is a small isometric game using public
2235
+ 2D HUD and 3D scene endpoints on separate canvases. Build Core first, then run
2236
+ `pnpm example:courier`. It demonstrates picking/keyboard navigation, camera
2237
+ projection, animated glTF, pause/save/load and teardown.