@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.
- package/README.md +1035 -10
- package/THIRD_PARTY_NOTICES.md +26 -0
- package/dist/2d/accessibility.d.ts +2 -0
- package/dist/2d/accessibility.js +171 -0
- package/dist/2d/commands.d.ts +2 -0
- package/dist/2d/commands.js +80 -0
- package/dist/2d/effects.d.ts +10 -0
- package/dist/2d/effects.js +566 -0
- package/dist/2d/ktx2.d.ts +5 -0
- package/dist/2d/ktx2.js +542 -0
- package/dist/2d/lighting.d.ts +3 -0
- package/dist/2d/lighting.js +495 -0
- package/dist/2d/lottie.d.ts +3 -0
- package/dist/2d/lottie.js +254 -0
- package/dist/2d/meshes.d.ts +4 -0
- package/dist/2d/meshes.js +451 -0
- package/dist/2d/primitives.d.ts +3 -0
- package/dist/2d/primitives.js +85 -0
- package/dist/2d/render-textures.d.ts +3 -0
- package/dist/2d/render-textures.js +539 -0
- package/dist/2d/svg/documents.d.ts +5 -0
- package/dist/2d/svg/documents.js +7 -0
- package/dist/2d/svg/renderer.d.ts +3 -0
- package/dist/2d/svg/renderer.js +222 -0
- package/dist/2d/svg.d.ts +3 -0
- package/dist/2d/svg.js +4 -0
- package/dist/2d/tools.d.ts +2 -0
- package/dist/2d/tools.js +100 -0
- package/dist/2d/video.d.ts +5 -0
- package/dist/2d/video.js +90 -0
- package/dist/2d.d.ts +2 -0
- package/dist/2d.js +220 -0
- package/dist/3d/animation.d.ts +8 -0
- package/dist/3d/animation.js +1396 -0
- package/dist/3d/area-lights.d.ts +2 -0
- package/dist/3d/area-lights.js +19 -0
- package/dist/3d/audio.d.ts +4 -0
- package/dist/3d/audio.js +500 -0
- package/dist/3d/character.d.ts +2 -0
- package/dist/3d/character.js +136 -0
- package/dist/3d/collision.d.ts +3 -0
- package/dist/3d/collision.js +387 -0
- package/dist/3d/commands.d.ts +2 -0
- package/dist/3d/commands.js +108 -0
- package/dist/3d/controls.d.ts +8 -0
- package/dist/3d/controls.js +1041 -0
- package/dist/3d/documents.d.ts +5 -0
- package/dist/3d/documents.js +227 -0
- package/dist/3d/effects.d.ts +5 -0
- package/dist/3d/effects.js +1986 -0
- package/dist/3d/export.d.ts +4 -0
- package/dist/3d/export.js +347 -0
- package/dist/3d/fbx.d.ts +2 -0
- package/dist/3d/fbx.js +784 -0
- package/dist/3d/gltf.d.ts +2 -0
- package/dist/3d/gltf.js +5 -0
- package/dist/3d/helpers.d.ts +5 -0
- package/dist/3d/helpers.js +191 -0
- package/dist/3d/ik.d.ts +9 -0
- package/dist/3d/ik.js +777 -0
- package/dist/3d/loaders.d.ts +17 -0
- package/dist/3d/loaders.js +1406 -0
- package/dist/3d/nodes.d.ts +8 -0
- package/dist/3d/nodes.js +49 -0
- package/dist/3d/particles.d.ts +5 -0
- package/dist/3d/particles.js +1574 -0
- package/dist/3d/physics/backend.d.ts +7 -0
- package/dist/3d/physics/backend.js +1 -0
- package/dist/3d/physics/rapier.d.ts +3 -0
- package/dist/3d/physics/rapier.js +765 -0
- package/dist/3d/physics.d.ts +5 -0
- package/dist/3d/physics.js +3346 -0
- package/dist/3d/splats.d.ts +7 -0
- package/dist/3d/splats.js +862 -0
- package/dist/3d/text.d.ts +5 -0
- package/dist/3d/text.js +1043 -0
- package/dist/3d/tiles.d.ts +24 -0
- package/dist/3d/tiles.js +1705 -0
- package/dist/3d/tools.d.ts +12 -0
- package/dist/3d/tools.js +338 -0
- package/dist/3d/usdz.d.ts +2 -0
- package/dist/3d/usdz.js +634 -0
- package/dist/3d/xr.d.ts +2 -0
- package/dist/3d/xr.js +202 -0
- package/dist/3d-B4jWF8Qb.js +5591 -0
- package/dist/3d.d.ts +40 -0
- package/dist/3d.js +44 -0
- package/dist/Capsule-BFVpZfvc.js +44 -0
- package/dist/Clip-CAN7t03k.js +204 -0
- package/dist/Color-vuv9UnoY.js +34 -0
- package/dist/DeformedMesh-CPi0P_vc.js +280 -0
- package/dist/Document-DCVEZSvM.js +415 -0
- package/dist/Errors-B2ekO9bZ.js +30 -0
- package/dist/Features-BsjmePtc.js +557 -0
- package/dist/GLTFResourceIO-CYJyCUTt.js +124 -0
- package/dist/GPUParticleState-CQlNpoDa.js +545 -0
- package/dist/Geometry-DytO490z.js +227 -0
- package/dist/Inflate-DWw0V-Up.js +42 -0
- package/dist/InstancedMesh-DPrgrw5z.js +527 -0
- package/dist/Limits-Bw5XQdFr.js +20 -0
- package/dist/LineHelper-Ad0z9uDi.js +131 -0
- package/dist/LoaderIO-BwrM84OM.js +114 -0
- package/dist/Material-BpfLPmK9.js +777 -0
- package/dist/Mesh-BaRxAAJq.js +209 -0
- package/dist/Node-QfgAE2_v.js +877 -0
- package/dist/NovaAssetRegistry-p2QlCwvT.js +1168 -0
- package/dist/NovaNode-CBZ-Ol-W.js +2016 -0
- package/dist/NovaRenderCommandWriter-CWQRa42y.js +1949 -0
- package/dist/NovaTextSelectionService-CipuujCT.js +18526 -0
- package/dist/NovaWebGLProgram-BO250QNF.js +97 -0
- package/dist/Options-CajE7LLJ.js +15 -0
- package/dist/PolygonMesh-D4PnnfIo.js +657 -0
- package/dist/Ready-BzyhRtjD.js +21 -0
- package/dist/Scene-CDfNgf9I.js +911 -0
- package/dist/Shader-b6_HDndT.js +48 -0
- package/dist/SplatShader-wJ6GJ3vo.js +130 -0
- package/dist/Texture-dTKMlTpK.js +267 -0
- package/dist/TextureLoader-CfDzdy2m.js +411 -0
- package/dist/Textures-CGL4Kf-8.js +651 -0
- package/dist/ToneMapping-D9IWvN0u.js +46 -0
- package/dist/WebGPURenderer-DjD0IxVC.js +4921 -0
- package/dist/ZipReader-C-MSEsSr.js +84 -0
- package/dist/core.js +218 -24024
- package/dist/domain/types/base.types.d.ts +18 -9
- package/dist/domain/types/component.types.d.ts +5 -5
- package/dist/domain/types/cursor.types.d.ts +1 -1
- package/dist/domain/types/diagnostics.types.d.ts +2 -0
- package/dist/domain/types/export.types.d.ts +2 -2
- package/dist/domain/types/hit-test.types.d.ts +1 -1
- package/dist/domain/types/motion.types.d.ts +2 -2
- package/dist/domain/types/renderer.types.d.ts +88 -4
- package/dist/domain/types/rendering/index.d.ts +29 -4
- package/dist/domain/types/sound.types.d.ts +1 -1
- package/dist/domain/types/theme.types.d.ts +1 -1
- package/dist/domain/utils/bounds.d.ts +1 -1
- package/dist/domain/utils/nova-text.d.ts +9 -0
- package/dist/domain/utils/schemaBounds.d.ts +2 -2
- package/dist/export-svg-document-ChaNXMaG.js +668 -0
- package/dist/features/3d/Errors.d.ts +57 -0
- package/dist/features/3d/Nova3DApp.d.ts +429 -0
- package/dist/features/3d/animation/Animator.d.ts +260 -0
- package/dist/features/3d/animation/Clip.d.ts +74 -0
- package/dist/features/3d/animation/Graph.d.ts +158 -0
- package/dist/features/3d/animation/Mask.d.ts +40 -0
- package/dist/features/3d/audio/Audio.d.ts +114 -0
- package/dist/features/3d/audio/Sound.d.ts +133 -0
- package/dist/features/3d/character/CharacterController.d.ts +61 -0
- package/dist/features/3d/collision/Capsule.d.ts +25 -0
- package/dist/features/3d/collision/Octree.d.ts +94 -0
- package/dist/features/3d/controls/CameraMotionControls.d.ts +154 -0
- package/dist/features/3d/controls/CameraOrientation.d.ts +47 -0
- package/dist/features/3d/controls/OrbitControls.d.ts +73 -0
- package/dist/features/3d/controls/PointerGesture.d.ts +25 -0
- package/dist/features/3d/controls/PointerLock.d.ts +36 -0
- package/dist/features/3d/controls/Snapping.d.ts +32 -0
- package/dist/features/3d/controls/TransformGizmo.d.ts +79 -0
- package/dist/features/3d/deformation/DeformationGPU.d.ts +52 -0
- package/dist/features/3d/deformation/DeformationShader.d.ts +2 -0
- package/dist/features/3d/deformation/DeformedMesh.d.ts +36 -0
- package/dist/features/3d/deformation/GeometryDeformation.d.ts +25 -0
- package/dist/features/3d/documents/Document.d.ts +59 -0
- package/dist/features/3d/documents/DocumentCommands.d.ts +45 -0
- package/dist/features/3d/documents/DocumentSchema.d.ts +18 -0
- package/dist/features/3d/documents/DocumentTransform.d.ts +4 -0
- package/dist/features/3d/documents/DocumentTypes.d.ts +182 -0
- package/dist/features/3d/documents/DocumentValidation.d.ts +18 -0
- package/dist/features/3d/documents/Projection.d.ts +65 -0
- package/dist/features/3d/effects/CubeLUT.d.ts +24 -0
- package/dist/features/3d/effects/Effects.d.ts +32 -0
- package/dist/features/3d/effects/EffectsGPU.d.ts +80 -0
- package/dist/features/3d/effects/EffectsPlan.d.ts +268 -0
- package/dist/features/3d/effects/EffectsShaders.d.ts +35 -0
- package/dist/features/3d/export/GLTFExporter.d.ts +49 -0
- package/dist/features/3d/export/ThreeMFExporter.d.ts +19 -0
- package/dist/features/3d/export/ZipWriter.d.ts +9 -0
- package/dist/features/3d/fbx/FBXLoader.d.ts +26 -0
- package/dist/features/3d/fbx/FBXParser.d.ts +35 -0
- package/dist/features/3d/fbx/FBXScene.d.ts +20 -0
- package/dist/features/3d/gltf/GLTFLoader.d.ts +16 -0
- package/dist/features/3d/gltf/GLTFTypes.d.ts +64 -0
- package/dist/features/3d/gltf/services/GLTFBinary.d.ts +21 -0
- package/dist/features/3d/gltf/services/GLTFGeometry.d.ts +14 -0
- package/dist/features/3d/gltf/services/GLTFResourceIO.d.ts +64 -0
- package/dist/features/3d/helpers/LineHelper.d.ts +51 -0
- package/dist/features/3d/helpers/StaticHelpers.d.ts +47 -0
- package/dist/features/3d/helpers/TrackedHelpers.d.ts +84 -0
- package/dist/features/3d/ik/ChainIK.d.ts +44 -0
- package/dist/features/3d/ik/IKChain.d.ts +92 -0
- package/dist/features/3d/ik/IKMath.d.ts +49 -0
- package/dist/features/3d/ik/IKSolver.d.ts +97 -0
- package/dist/features/3d/ik/LookAtIK.d.ts +58 -0
- package/dist/features/3d/ik/TwoBoneIK.d.ts +57 -0
- package/dist/features/3d/import/ImportAnimation.d.ts +20 -0
- package/dist/features/3d/import/ImportMath.d.ts +42 -0
- package/dist/features/3d/import/ImportedModel.d.ts +135 -0
- package/dist/features/3d/import/Inflate.d.ts +5 -0
- package/dist/features/3d/import/ModelAsset.d.ts +149 -0
- package/dist/features/3d/import/PolygonMesh.d.ts +54 -0
- package/dist/features/3d/lights/AreaLightTables.d.ts +8 -0
- package/dist/features/3d/lights/AreaLights.d.ts +11 -0
- package/dist/features/3d/loaders/EXRCompression.d.ts +13 -0
- package/dist/features/3d/loaders/EXRLoader.d.ts +39 -0
- package/dist/features/3d/loaders/HDRLoader.d.ts +26 -0
- package/dist/features/3d/loaders/Limits.d.ts +70 -0
- package/dist/features/3d/loaders/LoaderBuffers.d.ts +42 -0
- package/dist/features/3d/loaders/LoaderIO.d.ts +81 -0
- package/dist/features/3d/loaders/LoaderModel.d.ts +80 -0
- package/dist/features/3d/loaders/LoaderText.d.ts +27 -0
- package/dist/features/3d/loaders/MTLLoader.d.ts +105 -0
- package/dist/features/3d/loaders/OBJLoader.d.ts +70 -0
- package/dist/features/3d/loaders/PLYLoader.d.ts +47 -0
- package/dist/features/3d/loaders/STLLoader.d.ts +27 -0
- package/dist/features/3d/model/Camera.d.ts +33 -0
- package/dist/features/3d/model/Environment.d.ts +31 -0
- package/dist/features/3d/model/Geometry.d.ts +59 -0
- package/dist/features/3d/model/InstancedMesh.d.ts +134 -0
- package/dist/features/3d/model/LOD.d.ts +31 -0
- package/dist/features/3d/model/Light.d.ts +200 -0
- package/dist/features/3d/model/Material.d.ts +308 -0
- package/dist/features/3d/model/MaterialExtensions.d.ts +200 -0
- package/dist/features/3d/model/Mesh.d.ts +92 -0
- package/dist/features/3d/model/Node.d.ts +87 -0
- package/dist/features/3d/model/ReflectionProbe.d.ts +45 -0
- package/dist/features/3d/model/RenderTarget.d.ts +41 -0
- package/dist/features/3d/model/Scene.d.ts +173 -0
- package/dist/features/3d/model/Texture.d.ts +143 -0
- package/dist/features/3d/nodes/Nodes.d.ts +8 -0
- package/dist/features/3d/nodes/ShaderNode.d.ts +240 -0
- package/dist/features/3d/particles/GPUParticleSchedule.d.ts +67 -0
- package/dist/features/3d/particles/GPUParticleShaders.d.ts +19 -0
- package/dist/features/3d/particles/GPUParticleState.d.ts +106 -0
- package/dist/features/3d/particles/GPUParticleSystem.d.ts +192 -0
- package/dist/features/3d/particles/ParticleCurves.d.ts +34 -0
- package/dist/features/3d/particles/ParticleOptions.d.ts +78 -0
- package/dist/features/3d/particles/ParticleSystem.d.ts +368 -0
- package/dist/features/3d/physics/PhysicsBackend.d.ts +352 -0
- package/dist/features/3d/physics/PhysicsDebug.d.ts +24 -0
- package/dist/features/3d/physics/PhysicsWorld.d.ts +352 -0
- package/dist/features/3d/physics/basic/BasicCollision.d.ts +75 -0
- package/dist/features/3d/physics/basic/BasicPhysics.d.ts +24 -0
- package/dist/features/3d/physics/basic/BasicShapes.d.ts +103 -0
- package/dist/features/3d/physics/rapier/ContactBuffer.d.ts +32 -0
- package/dist/features/3d/physics/rapier/RapierBackend.d.ts +17 -0
- package/dist/features/3d/physics/rapier/RapierShapes.d.ts +4 -0
- package/dist/features/3d/physics/rapier/RapierWorld.d.ts +198 -0
- package/dist/features/3d/physics/rapier/Validation.d.ts +8 -0
- package/dist/features/3d/services/Background.d.ts +22 -0
- package/dist/features/3d/services/BasicShader.d.ts +55 -0
- package/dist/features/3d/services/ClusteredLights.d.ts +69 -0
- package/dist/features/3d/services/DrawOrder.d.ts +37 -0
- package/dist/features/3d/services/EffectsProcessor.d.ts +38 -0
- package/dist/features/3d/services/EnvironmentBRDF.d.ts +35 -0
- package/dist/features/3d/services/EnvironmentMaps.d.ts +55 -0
- package/dist/features/3d/services/FogShader.d.ts +6 -0
- package/dist/features/3d/services/Frustum.d.ts +7 -0
- package/dist/features/3d/services/GLState.d.ts +86 -0
- package/dist/features/3d/services/GPUPicker.d.ts +31 -0
- package/dist/features/3d/services/InstanceShader.d.ts +3 -0
- package/dist/features/3d/services/LineProgram.d.ts +32 -0
- package/dist/features/3d/services/PBRProgram.d.ts +115 -0
- package/dist/features/3d/services/Renderer.d.ts +50 -0
- package/dist/features/3d/services/Shader.d.ts +22 -0
- package/dist/features/3d/services/ShaderProgram.d.ts +38 -0
- package/dist/features/3d/services/ShadowMaps.d.ts +97 -0
- package/dist/features/3d/services/SpatialIndex.d.ts +16 -0
- package/dist/features/3d/services/TextureLoader.d.ts +40 -0
- package/dist/features/3d/services/TextureMipmaps.d.ts +42 -0
- package/dist/features/3d/services/ToneMapping.d.ts +12 -0
- package/dist/features/3d/services/WebGLRenderer.d.ts +261 -0
- package/dist/features/3d/splats/SplatData.d.ts +136 -0
- package/dist/features/3d/splats/SplatLoaders.d.ts +64 -0
- package/dist/features/3d/splats/SplatShader.d.ts +14 -0
- package/dist/features/3d/splats/SplatSort.d.ts +69 -0
- package/dist/features/3d/splats/Splats.d.ts +116 -0
- package/dist/features/3d/text/FontAtlas.d.ts +246 -0
- package/dist/features/3d/text/SDF.d.ts +28 -0
- package/dist/features/3d/text/Text.d.ts +179 -0
- package/dist/features/3d/text/TextLayout.d.ts +73 -0
- package/dist/features/3d/text/TextShader.d.ts +12 -0
- package/dist/features/3d/tiles/BoundingVolume.d.ts +43 -0
- package/dist/features/3d/tiles/Geodesy.d.ts +106 -0
- package/dist/features/3d/tiles/GlobeControls.d.ts +147 -0
- package/dist/features/3d/tiles/TileContent.d.ts +35 -0
- package/dist/features/3d/tiles/TileFormats.d.ts +77 -0
- package/dist/features/3d/tiles/Tiles3D.d.ts +236 -0
- package/dist/features/3d/tiles/Tileset.d.ts +81 -0
- package/dist/features/3d/tools/BatchedMesh.d.ts +74 -0
- package/dist/features/3d/tools/CanvasSurface.d.ts +81 -0
- package/dist/features/3d/tools/Color.d.ts +11 -0
- package/dist/features/3d/tools/MergeGeometries.d.ts +22 -0
- package/dist/features/3d/tools/Options.d.ts +15 -0
- package/dist/features/3d/tools/Polyhedra.d.ts +30 -0
- package/dist/features/3d/tools/PrimitiveBuffers.d.ts +42 -0
- package/dist/features/3d/tools/Primitives.d.ts +164 -0
- package/dist/features/3d/tools/Ready.d.ts +12 -0
- package/dist/features/3d/tools/SpatialMath.d.ts +57 -0
- package/dist/features/3d/tools/SphericalHarmonics.d.ts +9 -0
- package/dist/features/3d/tools/math/mat3.d.ts +7 -0
- package/dist/features/3d/tools/math/mat4.d.ts +19 -0
- package/dist/features/3d/tools/math/quat.d.ts +6 -0
- package/dist/features/3d/tools/math/vec3.d.ts +16 -0
- package/dist/features/3d/tools/math/vec4.d.ts +5 -0
- package/dist/features/3d/types.d.ts +359 -0
- package/dist/features/3d/usdz/USDAParser.d.ts +50 -0
- package/dist/features/3d/usdz/USDScene.d.ts +20 -0
- package/dist/features/3d/usdz/USDZLoader.d.ts +27 -0
- package/dist/features/3d/usdz/ZipReader.d.ts +16 -0
- package/dist/features/3d/webgpu/Backend.d.ts +40 -0
- package/dist/features/3d/webgpu/BasicShader.d.ts +10 -0
- package/dist/features/3d/webgpu/Constants.d.ts +32 -0
- package/dist/features/3d/webgpu/Deformation.d.ts +71 -0
- package/dist/features/3d/webgpu/Environment.d.ts +66 -0
- package/dist/features/3d/webgpu/Features.d.ts +68 -0
- package/dist/features/3d/webgpu/Layouts.d.ts +27 -0
- package/dist/features/3d/webgpu/Lines.d.ts +40 -0
- package/dist/features/3d/webgpu/LitExtras.d.ts +46 -0
- package/dist/features/3d/webgpu/LitFeatures.d.ts +41 -0
- package/dist/features/3d/webgpu/LitScene.d.ts +60 -0
- package/dist/features/3d/webgpu/LitShader.d.ts +68 -0
- package/dist/features/3d/webgpu/Particles.d.ts +114 -0
- package/dist/features/3d/webgpu/Picking.d.ts +59 -0
- package/dist/features/3d/webgpu/PipelineKey.d.ts +33 -0
- package/dist/features/3d/webgpu/Points.d.ts +41 -0
- package/dist/features/3d/webgpu/Probes.d.ts +45 -0
- package/dist/features/3d/webgpu/ShaderChunks.d.ts +18 -0
- package/dist/features/3d/webgpu/ShaderMaterial.d.ts +57 -0
- package/dist/features/3d/webgpu/ShaderMaterialSource.d.ts +5 -0
- package/dist/features/3d/webgpu/Shadows.d.ts +49 -0
- package/dist/features/3d/webgpu/Splats.d.ts +47 -0
- package/dist/features/3d/webgpu/Textures.d.ts +52 -0
- package/dist/features/3d/webgpu/Transmission.d.ts +30 -0
- package/dist/features/3d/webgpu/UniformLayout.d.ts +30 -0
- package/dist/features/3d/webgpu/UtilityShaders.d.ts +38 -0
- package/dist/features/3d/webgpu/WebGPURenderer.d.ts +327 -0
- package/dist/features/3d/webgpu/effects/EffectsShaders.d.ts +74 -0
- package/dist/features/3d/webgpu/effects/WebGPUEffects.d.ts +140 -0
- package/dist/features/3d/xr/XR.d.ts +100 -0
- package/dist/gltf-By-n0qEg.js +960 -0
- package/dist/index.d.ts +86 -81
- package/dist/model/document-actions/document-commands.d.ts +18 -0
- package/dist/model/documents/svg/create-svg-document-renderer.d.ts +32 -0
- package/dist/model/documents/svg/export-svg-document.d.ts +5 -0
- package/dist/model/documents/svg/import-svg-document.d.ts +6 -0
- package/dist/model/documents/svg/svg-document.types.d.ts +111 -0
- package/dist/model/documents/svg/svg-values.d.ts +16 -0
- package/dist/model/documents/svg/svg-xml.d.ts +18 -0
- package/dist/model/input/NovaInputProxy_Adapter.d.ts +2 -1
- package/dist/model/input/NovaInputValidationController.d.ts +1 -1
- package/dist/model/input/NovaTextInputController.d.ts +1 -1
- package/dist/model/input/NovaTextLayoutEngine.d.ts +2 -6
- package/dist/model/input/index.d.ts +7 -7
- package/dist/model/input/nova-input.types.d.ts +1 -1
- package/dist/model/lighting/LightingRenderer2D.d.ts +58 -0
- package/dist/model/lighting/NovaLighting2D.d.ts +56 -0
- package/dist/model/lighting/lighting-shaders.d.ts +3 -0
- package/dist/model/lighting/lighting-state.d.ts +27 -0
- package/dist/model/lighting/lighting.types.d.ts +107 -0
- package/dist/model/lottie/LottieNode.d.ts +4 -0
- package/dist/model/lottie/lottie.types.d.ts +83 -0
- package/dist/model/lottie/prepare-lottie.d.ts +3 -0
- package/dist/model/lottie/sample-position.d.ts +9 -0
- package/dist/model/motion/NovaMotionEngine.d.ts +3 -3
- package/dist/model/motion/nova-motion-easing.d.ts +1 -1
- package/dist/model/motion/nova-motion-interpolation.d.ts +1 -1
- package/dist/model/motion/nova-motion-presets.d.ts +2 -2
- package/dist/model/motion/nova-motion-timeline.d.ts +1 -1
- package/dist/model/platform/NovaCanvas.d.ts +7 -6
- package/dist/model/primitives/NovaPrimitiveUnsupportedError.d.ts +13 -0
- package/dist/model/primitives/definePrimitive.d.ts +5 -0
- package/dist/model/primitives/primitive.types.d.ts +28 -0
- package/dist/model/render/backends/canvas2d/NovaCanvas2DTargetManager.d.ts +3 -3
- package/dist/model/render/backends/canvas2d/NovaRenderer2D.d.ts +61 -15
- package/dist/model/render/backends/canvas2d/nova-canvas-blend.d.ts +5 -0
- package/dist/model/render/backends/nova-render-backend-factory.d.ts +6 -6
- package/dist/model/render/backends/nova-render-backend.d.ts +8 -2
- package/dist/model/render/backends/webgl/NovaRendererWebGL.d.ts +32 -11
- package/dist/model/render/backends/webgl/NovaStreamCacheIdleLedger.d.ts +12 -1
- package/dist/model/render/backends/webgl/NovaWebGLBatcher.d.ts +1 -1
- package/dist/model/render/backends/webgl/NovaWebGLCircleImagePass.d.ts +23 -0
- package/dist/model/render/backends/webgl/NovaWebGLCompositionPass.d.ts +9 -0
- package/dist/model/render/backends/webgl/NovaWebGLDevice.d.ts +3 -1
- package/dist/model/render/backends/webgl/NovaWebGLDiagnostics.d.ts +1 -1
- package/dist/model/render/backends/webgl/NovaWebGLFrameRenderer.d.ts +162 -53
- package/dist/model/render/backends/webgl/NovaWebGLPathClipPass.d.ts +13 -0
- package/dist/model/render/backends/webgl/NovaWebGLPathUnion.d.ts +23 -0
- package/dist/model/render/compiler/NovaRenderBuilder.d.ts +24 -10
- package/dist/model/render/compiler/NovaRenderCommandWriter.d.ts +10 -5
- package/dist/model/render/compiler/NovaRenderCompiler.d.ts +7 -6
- package/dist/model/render/compiler/NovaRenderFrameBuilder.d.ts +4 -3
- package/dist/model/render/effects/blur.d.ts +8 -0
- package/dist/model/render/effects/color-matrix.d.ts +8 -0
- package/dist/model/render/effects/drop-shadow.d.ts +18 -0
- package/dist/model/render/effects/nova-effect-registry.d.ts +66 -0
- package/dist/model/render/effects/nova-gaussian-kernel.d.ts +7 -0
- package/dist/model/render/effects/nova-gaussian-textures.d.ts +11 -0
- package/dist/model/render/effects/shader-effect.d.ts +64 -0
- package/dist/model/render/geometry/nova-alpha-mask.d.ts +5 -0
- package/dist/model/render/geometry/nova-composition.d.ts +9 -0
- package/dist/model/render/geometry/nova-node-clip.d.ts +17 -0
- package/dist/model/render/geometry/nova-path-geometry.d.ts +24 -0
- package/dist/model/render/geometry/nova-path-tessellation.d.ts +7 -0
- package/dist/model/render/geometry/nova-polygon-triangulation.d.ts +1 -1
- package/dist/model/render/graph/NovaRectBatchBuffer.d.ts +58 -0
- package/dist/model/render/graph/NovaRenderGraph.d.ts +40 -6
- package/dist/model/render/graph/NovaRenderHitIndex.d.ts +1 -1
- package/dist/model/render/graph/nova-auto-rect.d.ts +1 -1
- package/dist/model/render/graph/nova-linear-rect-repack.d.ts +4 -4
- package/dist/model/render/graph/nova-linear-rect-transition.d.ts +2 -2
- package/dist/model/render/graph/nova-render-culling.d.ts +2 -2
- package/dist/model/render/graph/nova-render-dirty-items.d.ts +1 -1
- package/dist/model/render/graph/nova-render-group.d.ts +1 -1
- package/dist/model/render/graph/nova-render-item.d.ts +2 -2
- package/dist/model/render/graph/nova-render-layer.d.ts +1 -1
- package/dist/model/render/graph/nova-render-payload-snapshot.d.ts +3 -1
- package/dist/model/render/graph/nova-render-program.d.ts +5 -3
- package/dist/model/render/graph/nova-render-sequence.d.ts +1 -1
- package/dist/model/render/graph/nova-render-stream.d.ts +2 -2
- package/dist/model/render/ktx2/BasisSession.d.ts +45 -0
- package/dist/model/render/ktx2/KTX2Container.d.ts +26 -0
- package/dist/model/render/ktx2/KTX2Loader.d.ts +55 -0
- package/dist/model/render/meshes/MeshNode.d.ts +13 -0
- package/dist/model/render/meshes/NovaMeshWebGLDevice.d.ts +27 -0
- package/dist/model/render/meshes/geometry.d.ts +7 -0
- package/dist/model/render/meshes/mesh.d.ts +3 -0
- package/dist/model/render/meshes/mesh.types.d.ts +116 -0
- package/dist/model/render/meshes/nova-mesh-registry.d.ts +55 -0
- package/dist/model/render/orchestration/NovaRenderOrchestrator.d.ts +25 -3
- package/dist/model/render/policy/nova-render-policy.d.ts +1 -1
- package/dist/model/render/resources/NovaGlyphAtlasManager.d.ts +2 -2
- package/dist/model/render/resources/NovaTextAtlasManager.d.ts +3 -3
- package/dist/model/render/resources/NovaTextLayoutEngine.d.ts +1 -1
- package/dist/model/render/resources/nova-bitmap-upload.d.ts +10 -0
- package/dist/model/render/schema/NovaRenderContext.d.ts +6 -4
- package/dist/model/render/schema/nova-style-compiler.d.ts +5 -2
- package/dist/model/render/targets/NovaNodeRenderTextureSource.d.ts +29 -0
- package/dist/model/render/targets/NovaRenderTargetManager.d.ts +1 -1
- package/dist/model/render/targets/NovaRenderTexture.d.ts +57 -0
- package/dist/model/render/targets/nova-render-target-refs.d.ts +5 -0
- package/dist/model/render/targets/nova-render-target-resource.d.ts +1 -1
- package/dist/model/render/targets/nova-render-texture-runtime.d.ts +71 -0
- package/dist/model/render/textures/nova-compressed-image.d.ts +20 -0
- package/dist/model/render/utils/nova-icon-rendering.d.ts +3 -1
- package/dist/model/render/utils/nova-image-geometry.d.ts +11 -0
- package/dist/model/render/utils/nova-markdown-layout.d.ts +19 -0
- package/dist/model/render/utils/nova-text-paint.d.ts +26 -0
- package/dist/model/render/utils/nova-wrapped-text-layout.d.ts +19 -0
- package/dist/model/runtime/app/Nova.d.ts +35 -35
- package/dist/model/runtime/app/NovaApp.d.ts +58 -30
- package/dist/model/runtime/app/NovaRaphRuntime.d.ts +2 -2
- package/dist/model/runtime/app/createNovaRaphRuntime.d.ts +3 -3
- package/dist/model/runtime/assets/NovaAssetRegistry.d.ts +89 -2
- package/dist/model/runtime/assets/NovaVideoTexture.d.ts +38 -0
- package/dist/model/runtime/assets/nova-render-texture-image-identity.d.ts +4 -0
- package/dist/model/runtime/commands/NovaCommandBus.d.ts +1 -1
- package/dist/model/runtime/components/NovaComponentNode.d.ts +6 -6
- package/dist/model/runtime/components/NovaComponentRegistry.d.ts +1 -1
- package/dist/model/runtime/components/NovaSchemaRegistry.d.ts +7 -6
- package/dist/model/runtime/components/nova-component-metadata.d.ts +1 -1
- package/dist/model/runtime/components/nova-component.decorator.d.ts +2 -2
- package/dist/model/runtime/components/nova-defined-component.d.ts +3 -3
- package/dist/model/runtime/context/nova-context.d.ts +1 -1
- package/dist/model/runtime/cursor/NovaCursorManager.d.ts +3 -3
- package/dist/model/runtime/diagnostics/NovaDiagnostics_Module.d.ts +3 -3
- package/dist/model/runtime/interaction/NovaEvents.d.ts +16 -6
- package/dist/model/runtime/interaction/NovaHitIndex.d.ts +1 -1
- package/dist/model/runtime/interaction/NovaSpatialIndex.d.ts +2 -2
- package/dist/model/runtime/scene/NovaScene.d.ts +3 -3
- package/dist/model/runtime/scene/nova-scene-components.d.ts +6 -6
- package/dist/model/runtime/state/nova-store-decorators.d.ts +1 -1
- package/dist/model/runtime/state/nova-store-runtime.d.ts +1 -1
- package/dist/model/runtime/state/nova-store-tracking.d.ts +7 -3
- package/dist/model/runtime/sync/NovaSyncScope.d.ts +11 -2
- package/dist/model/runtime/sync/nova-sync-context.d.ts +2 -2
- package/dist/model/runtime/sync/nova-sync-ports.d.ts +2 -2
- package/dist/model/runtime/sync/nova-sync.types.d.ts +15 -3
- package/dist/model/runtime/template/NovaTemplateRuntime.d.ts +6 -6
- package/dist/model/runtime/tree/NovaContainer.d.ts +4 -4
- package/dist/model/runtime/tree/NovaNode.d.ts +58 -18
- package/dist/model/runtime/tree/NovaRaphNode.d.ts +8 -2
- package/dist/model/runtime/tree/NovaSurface.d.ts +32 -10
- package/dist/model/runtime/tree/nova-node-capture-invalidation.d.ts +11 -0
- package/dist/model/semantic/NovaSemanticService.d.ts +1 -1
- package/dist/model/semantic/browser/createAccessibilityBridge.d.ts +29 -0
- package/dist/model/sound/NovaSoundEngine.d.ts +3 -2
- package/dist/model/text-selection/NovaTextSelectionService.d.ts +2 -2
- package/dist/model/text-selection/index.d.ts +2 -2
- package/dist/model/text-selection/nova-text-selection.types.d.ts +1 -1
- package/dist/model/theme/NovaGlobalThemeRegistry.d.ts +2 -2
- package/dist/model/theme/NovaThemeService.d.ts +5 -3
- package/dist/model/theme/createTokenTheme.d.ts +15 -0
- package/dist/model/tools/transform-tools.d.ts +43 -0
- package/dist/nodes--Ds4IS2h.js +621 -0
- package/dist/nova-color-parser-BCN_rFRN.js +250 -0
- package/dist/nova-compressed-image-CE2Ya9Xa.js +46 -0
- package/dist/nova-mesh-registry-B7Xz5mhU.js +24 -0
- package/dist/nova-render-texture-image-identity-DQ09XFKs.js +15 -0
- package/dist/nova-text-paint-CcntsRjI.js +48 -0
- package/dist/tokens.d.ts +2 -0
- package/dist/tokens.js +50 -0
- package/dist/vec4-BTNv1fUp.js +20 -0
- 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 {
|
|
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.
|
|
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()`
|
|
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.
|
|
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.
|
|
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
|
|
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
|
-
|
|
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.
|