@egret/runtime 0.0.0-stage → 7.0.1-rc.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (155) hide show
  1. package/LICENSE +201 -0
  2. package/NOTICE +21 -0
  3. package/README.md +70 -2
  4. package/README.zh-CN.md +71 -0
  5. package/dist/AssetLease.d.ts +23 -0
  6. package/dist/AssetLease.js +69 -0
  7. package/dist/AssetManager.d.ts +56 -0
  8. package/dist/AssetManager.js +451 -0
  9. package/dist/AssetRef.d.ts +20 -0
  10. package/dist/AssetRef.js +32 -0
  11. package/dist/Bitmap.d.ts +40 -0
  12. package/dist/Bitmap.js +545 -0
  13. package/dist/ByteReader.d.ts +30 -0
  14. package/dist/ByteReader.js +177 -0
  15. package/dist/ByteWriter.d.ts +29 -0
  16. package/dist/ByteWriter.js +180 -0
  17. package/dist/CancellationController.d.ts +10 -0
  18. package/dist/CancellationController.js +66 -0
  19. package/dist/DisplayObject.d.ts +89 -0
  20. package/dist/DisplayObject.js +340 -0
  21. package/dist/DisplayObjectContainer.d.ts +28 -0
  22. package/dist/DisplayObjectContainer.js +226 -0
  23. package/dist/EgretError.d.ts +11 -0
  24. package/dist/EgretError.js +36 -0
  25. package/dist/Event.d.ts +45 -0
  26. package/dist/Event.js +84 -0
  27. package/dist/EventDispatcher.d.ts +24 -0
  28. package/dist/EventDispatcher.js +178 -0
  29. package/dist/Graphics.d.ts +106 -0
  30. package/dist/Graphics.js +504 -0
  31. package/dist/Mesh2D.d.ts +27 -0
  32. package/dist/Mesh2D.js +200 -0
  33. package/dist/NineSliceBitmap.d.ts +24 -0
  34. package/dist/NineSliceBitmap.js +164 -0
  35. package/dist/NineSliceGeometry2D.d.ts +18 -0
  36. package/dist/NineSliceGeometry2D.js +126 -0
  37. package/dist/Scope.d.ts +18 -0
  38. package/dist/Scope.js +133 -0
  39. package/dist/SequencePlayer.d.ts +12 -0
  40. package/dist/SequencePlayer.js +69 -0
  41. package/dist/Sprite.d.ts +8 -0
  42. package/dist/Sprite.js +12 -0
  43. package/dist/Stage.d.ts +14 -0
  44. package/dist/Stage.js +31 -0
  45. package/dist/Texture.d.ts +29 -0
  46. package/dist/Texture.js +177 -0
  47. package/dist/assetManagerOwnerState.d.ts +36 -0
  48. package/dist/assetManagerOwnerState.js +115 -0
  49. package/dist/assetState.d.ts +44 -0
  50. package/dist/assetState.js +2 -0
  51. package/dist/atlasFrameLayout.d.ts +21 -0
  52. package/dist/atlasFrameLayout.js +48 -0
  53. package/dist/bitmapDisplayState.d.ts +24 -0
  54. package/dist/bitmapDisplayState.js +22 -0
  55. package/dist/coordinateInverse.d.ts +4 -0
  56. package/dist/coordinateInverse.js +107 -0
  57. package/dist/diagnostics.d.ts +4 -0
  58. package/dist/diagnostics.js +13 -0
  59. package/dist/displayBounds.d.ts +9 -0
  60. package/dist/displayBounds.js +181 -0
  61. package/dist/displayCoordinates.d.ts +8 -0
  62. package/dist/displayCoordinates.js +81 -0
  63. package/dist/displayHitState.d.ts +18 -0
  64. package/dist/displayHitState.js +97 -0
  65. package/dist/displayHitTest.d.ts +8 -0
  66. package/dist/displayHitTest.js +219 -0
  67. package/dist/displayInputOperations.d.ts +12 -0
  68. package/dist/displayInputOperations.js +71 -0
  69. package/dist/displayTransform.d.ts +5 -0
  70. package/dist/displayTransform.js +38 -0
  71. package/dist/displayTreeState.d.ts +90 -0
  72. package/dist/displayTreeState.js +450 -0
  73. package/dist/displayVisualState.d.ts +74 -0
  74. package/dist/displayVisualState.js +140 -0
  75. package/dist/errorHelp.d.ts +14 -0
  76. package/dist/errorHelp.js +432 -0
  77. package/dist/errorHelpZh.d.ts +5 -0
  78. package/dist/errorHelpZh.js +340 -0
  79. package/dist/graphicsFill.d.ts +37 -0
  80. package/dist/graphicsFill.js +302 -0
  81. package/dist/graphicsShape.d.ts +144 -0
  82. package/dist/graphicsShape.js +755 -0
  83. package/dist/index.d.ts +50 -0
  84. package/dist/index.js +28 -0
  85. package/dist/input/PointerRouter.d.ts +4 -0
  86. package/dist/input/PointerRouter.js +453 -0
  87. package/dist/input/index.d.ts +3 -0
  88. package/dist/input/index.js +3 -0
  89. package/dist/input/types.d.ts +58 -0
  90. package/dist/input/types.js +3 -0
  91. package/dist/meshCaptureSnapshot.d.ts +5 -0
  92. package/dist/meshCaptureSnapshot.js +13 -0
  93. package/dist/meshDisplayState.d.ts +18 -0
  94. package/dist/meshDisplayState.js +21 -0
  95. package/dist/ownership.d.ts +75 -0
  96. package/dist/ownership.js +157 -0
  97. package/dist/paragraph/Paragraph.d.ts +13 -0
  98. package/dist/paragraph/Paragraph.js +193 -0
  99. package/dist/paragraph/ParagraphCache.d.ts +5 -0
  100. package/dist/paragraph/ParagraphCache.js +354 -0
  101. package/dist/paragraph/geometry.d.ts +4 -0
  102. package/dist/paragraph/geometry.js +180 -0
  103. package/dist/paragraph/index.d.ts +3 -0
  104. package/dist/paragraph/index.js +3 -0
  105. package/dist/paragraph/request.d.ts +6 -0
  106. package/dist/paragraph/request.js +191 -0
  107. package/dist/paragraph/types.d.ts +183 -0
  108. package/dist/paragraph/types.js +2 -0
  109. package/dist/preparedDisplaySubtree.d.ts +7 -0
  110. package/dist/preparedDisplaySubtree.js +205 -0
  111. package/dist/renderEffect.d.ts +47 -0
  112. package/dist/renderEffect.js +87 -0
  113. package/dist/sequenceClip.d.ts +42 -0
  114. package/dist/sequenceClip.js +196 -0
  115. package/dist/sharedFrameCapture.d.ts +24 -0
  116. package/dist/sharedFrameCapture.js +1069 -0
  117. package/dist/spriteSheet.d.ts +34 -0
  118. package/dist/spriteSheet.js +321 -0
  119. package/dist/srgbBytes.d.ts +3 -0
  120. package/dist/srgbBytes.js +64 -0
  121. package/dist/text/TextField.d.ts +13 -0
  122. package/dist/text/TextField.js +261 -0
  123. package/dist/text/TextRasterCache.d.ts +5 -0
  124. package/dist/text/TextRasterCache.js +1191 -0
  125. package/dist/text/budget.d.ts +51 -0
  126. package/dist/text/budget.js +116 -0
  127. package/dist/text/index.d.ts +4 -0
  128. package/dist/text/index.js +3 -0
  129. package/dist/text/plan.d.ts +16 -0
  130. package/dist/text/plan.js +238 -0
  131. package/dist/text/request.d.ts +44 -0
  132. package/dist/text/request.js +303 -0
  133. package/dist/text/types.d.ts +179 -0
  134. package/dist/text/types.js +2 -0
  135. package/dist/textDisplayState.d.ts +21 -0
  136. package/dist/textDisplayState.js +27 -0
  137. package/dist/ui/displayCommit.d.ts +43 -0
  138. package/dist/ui/displayCommit.js +376 -0
  139. package/dist/ui/editing.d.ts +3 -0
  140. package/dist/ui/editing.js +3 -0
  141. package/dist/ui/heightIndex.d.ts +35 -0
  142. package/dist/ui/heightIndex.js +295 -0
  143. package/dist/ui/index.d.ts +6 -0
  144. package/dist/ui/index.js +6 -0
  145. package/dist/ui/layout.d.ts +9 -0
  146. package/dist/ui/layout.js +349 -0
  147. package/dist/ui/managedState.d.ts +12 -0
  148. package/dist/ui/managedState.js +44 -0
  149. package/dist/ui/textEditState.d.ts +4 -0
  150. package/dist/ui/textEditState.js +206 -0
  151. package/dist/ui/textEditTypes.d.ts +48 -0
  152. package/dist/ui/textEditTypes.js +2 -0
  153. package/dist/ui/types.d.ts +99 -0
  154. package/dist/ui/types.js +2 -0
  155. package/package.json +44 -4
package/LICENSE ADDED
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright [yyyy] [name of copyright owner]
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
package/NOTICE ADDED
@@ -0,0 +1,21 @@
1
+ First-party code and documentation: Apache-2.0; see LICENSE.
2
+
3
+ robust-predicates 3.0.3 by Vladimir Agafonkin
4
+ https://github.com/mourner/robust-predicates
5
+ License: Unlicense. The unmodified license text is retained in
6
+ third-party/robust-predicates-3.0.3.LICENSE and the installed package.
7
+ Used through its public package root for orient2d in private DOM-free
8
+ rectangle preparation. This dependency does not establish native GPU,
9
+ browser bundle-size, performance or complete-engine acceptance.
10
+
11
+ jsonc-parser 3.3.1 by Microsoft Corporation
12
+ https://github.com/microsoft/node-jsonc-parser
13
+ License: MIT. The unmodified Microsoft copyright and permission notice is
14
+ retained in third-party/jsonc-parser-3.3.1.LICENSE and the installed package.
15
+ Only createScanner and visit are used through its public package root in
16
+ the private headless project adapters. First-party schema generation,
17
+ validation, canonical bytes, transactions and history are independently authored.
18
+ The 0.14.0 engineering preview has bounded headless implementation evidence;
19
+ editor, migration, browser/bundler, Native SDK and performance remain unaccepted.
20
+ Native Node public-root CJS interoperability is separate from the shipped
21
+ ESM entry's extensionless-import limitation.
package/README.md CHANGED
@@ -1,3 +1,71 @@
1
- # Temporary Holding Version
1
+ # @egret/runtime
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ English | [简体中文](README.zh-CN.md)
4
+
5
+ Egret's experimental logic package depends only on `@egret/contracts`. It receives event descriptors, synchronous cleanup values and narrow lifecycle ports injected by Engine, and provides cancellation, Scope, display trees, synchronous dispatch and CPU asset acquisition/leases. It maintains Scope ownership, object-to-Engine binding, parent/child relationships and event state.
6
+
7
+ ## Engineering preview 0.52.0 — display anchor offsets
8
+
9
+ Existing display classes inherit finite-number `anchorOffsetX` and `anchorOffsetY`, default +0. The authored pivot places scale/rotation coherently across coordinates, logical bounds, clipping, explicit picking and frame capture, with original zero-offset bytes retained. Read the [current contract](../../knowledge-base/en/docs/display-anchor-offsets-contract.md) and [bounded evidence](../../knowledge-base/en/docs/display-anchor-offsets-evidence.md).
10
+
11
+ **Historical module notes below retain their earlier cutoffs, dated before 0.52.0.** Their earlier pending statements describe those editions; the linked current evidence defines today's accepted scope. Complete EUI/layout and full Spine remain OPEN.
12
+
13
+ DisplayObjectContainer.getChildIndex(child: DisplayObject): number is a read-only query of the exact current direct child. It scans the authoritative private order in O(n), with no list snapshot/cache, tree mutation, owner transfer, resource operation or display callback. Sprite/Stage inherit it; root values/types, subpaths, dependencies and protocol are unchanged. Read the [0.50 contract](../../knowledge-base/en/docs/container-child-index-contract.md).
14
+
15
+ `DisplayObjectContainer.removeChildren(): void` clears a display layer while keeping its nodes, descendants, resources and cleanup owners alive. It authenticates the genuine receiver, checks Engine before receiver lifetime even when empty, preflights every direct edge and commits without caller hooks. Sprite and Stage inherit the method; root values/types, profiles, dependencies and protocol remain unchanged. Read the [0.49 contract](../../knowledge-base/en/docs/container-remove-children-contract.md).
16
+
17
+ Engineering preview 0.48.0 adds `NineSliceBitmap` and erased `NineSliceBitmapOptions` at the Runtime/Engine roots. It borrows a genuine Texture lease and resizes fixed-border NS1 content; both shared Hosts draw it. See the [contract](../../knowledge-base/en/docs/nine-slice-bitmap-contract.md) and [bounded evidence](../../knowledge-base/en/docs/nine-slice-bitmap-evidence.md).
18
+
19
+ Inherited `getBounds` reads authoritative receiver-local content with type-only `BoundsQueryOptions`, explicit node/primitive budgets and a fresh frozen result. Read the [bounds contract](../../knowledge-base/en/docs/display-content-bounds-contract.md).
20
+
21
+ Inherited display coordinate queries use authentic display state, bounded ancestor/lifetime checks and optional `CoordinateQueryOptions`. Read the [coordinate contract](../../knowledge-base/en/docs/display-coordinate-query-contract.md).
22
+
23
+ ## Ownership and cleanup
24
+
25
+ `EngineContext`, `createScope` and `createStage` serve internal engine assembly and are not exported by the public facade. Engine creates Scope, Stage and AssetManager. Asset types and references are factory-created and checked at runtime. Shared acquisition tasks and independent leases remain separate; see the [asset contract](../../knowledge-base/en/docs/resource-core-contract.md).
26
+
27
+ Scope registration handles recursion on the same value, state rechecks after user callbacks, late values during shutdown and ownership conflicts. Internal mounting and finalization preserve actual tree state without implicitly calling public `removeChild` overrides; the current contract has no mount/remove notifications. Cleanup failures are recorded individually while remaining listeners and subtrees continue to be processed. Recursive finalization respects the initiating root's owner boundary.
28
+
29
+ Failed signal registration withdraws the subscription and attempts adapter rollback. If a synchronous event handler returns a Promise, it is rejected synchronously and its rejection is observed.
30
+
31
+ ## Display and frame state
32
+
33
+ Internal visual state and iterative frame extraction retain authoritative tree order; public getters do not supply frame facts. Graphics belongs to its Sprite. Clip and rectangle values are copied and frozen so later edits cannot alter old frames. Detached but still-bound objects also obey engine closing restrictions.
34
+
35
+ Through the engine facade, `DisplayObject` exposes `x`, `y`, `scaleX`, `scaleY`, `rotation`, `alpha`, `visible` and `clipRect`; `Sprite.graphics` owns rectangle fills. `Engine.captureSharedFrame`/`renderSharedFrame` capture/submit immutable `SharedRenderFrame2D`. The browser Hosts are the separate `@egret/engine/webgpu` and `@egret/engine/webgl2` entries, while the root remains DOM-free. See the [shared render profile contract](../../knowledge-base/en/docs/shared-render-profile-contract.md); automatic frame scheduling is outside that contract.
36
+
37
+ ## Verification and scope
38
+
39
+ Behavioral tests consume the public built engine entry. Run `node tools/verify.mjs` from the repository root. Design and version-bound evidence are in the [knowledge base](../../knowledge-base/en/README.md) and [display/frame implementation record](../../knowledge-base/en/docs/display-and-frame-implementation-record.md); source attribution is in the [source record](../../source-origin.json).
40
+
41
+ Interfaces remain experimental. Full text, texture, animation, UI and 3D execution, Native support, target-device performance, editors, Agent services and complete migration require separate acceptance. Package version `0.0.0` and `private: true` remain unchanged; no npm publication follows from this guide. First-party code and this document use [Apache-2.0](../../LICENSE).
42
+
43
+ ## Explicit sequence animation
44
+
45
+ `createSequenceClip` owns validated atlas timing; `SequencePlayer` applies caller-supplied absolute seconds to one Bitmap and exact borrowed lease. Construction changes no crop; disposal releases no caller resource. There is no automatic scheduler. See the [contract and acceptance scope](../../knowledge-base/en/docs/sequence-player-contract.md) and public `examples/sequence-player` / `tools/sequence-player` guides.
46
+
47
+ ## Owned binary reading
48
+
49
+ The root exports `ByteReader` and the frozen `BYTE_READER_LIMITS`, plus type-only `ByteOrder`. Readers copy an eligible fixed ordinary Uint8Array payload, default to bigEndian, and support bounded atomic scalar/copy reads. Returned bytes are independent copies; disposal clears owned references. Existing Scope may own a reader through its disposable shape. Read the [BR1 contract](../../knowledge-base/en/docs/byte-reader-br1-contract.md) and [recorded verification scope](../../knowledge-base/en/docs/byte-reader-br1-evidence.md). No binary format, text encoding or legacy ByteArray compatibility is promised. The Main integration and publication checks remain pending at this preparation cutoff.
50
+
51
+ <!-- NS1-DOC-0.41.0-BEGIN -->
52
+ ## Engineering preview 0.41.0 — nine-slice stretch geometry NS1
53
+
54
+ **S094 / V045. Finite CPU, types, policy and browser observations accepted; complete publication gates and delivery remain PENDING.** Fixed-border stretch geometry reuses the existing Mesh2D texture lease; resizing replaces geometry. Runtime/engine roots expose one factory and two readonly types while retaining the original owned geometry identity.
55
+
56
+ Actual CPU checks passed 27/27: 11 NS groups, 6 Mesh groups and 10 geometry checks including nested cases. Positive type diagnostics were 0; the two intentional negative streams contained 41/35 actual diagnostics, totaling 76 precise location records. Strict type and policy guards exited 0; assigned policy controls passed 13/13. The actual browser completed 2 frames and 96 color-channel comparisons with verified cleanup; see the evidence for the exact environment and scope.
57
+
58
+ The original NSP09 13/12/1 failure and its finite test-input correction remain separate.
59
+
60
+ ByteWriter 0.40.0 merged through [PR #27](https://github.com/cnedwin/Egret_rebuild/pull/27), with Main `8e1509878252cc2a9295fcc56d7597877d023c85` and tree `ca1f2f176713e388e09016ae22d610c5c1b95201` read back. The mandatory push hook exited 0 with 63 publication and 2724 core checks. Zero remote statuses/check runs do not establish remote CI PASS. Earlier PENDING cutoffs and failure records remain preserved.
61
+
62
+ [contract](../../knowledge-base/en/docs/nine-slice-geometry-ns1-contract.md) / [evidence](../../knowledge-base/en/docs/nine-slice-geometry-ns1-evidence.md).
63
+
64
+ This bounded geometry increment contributes to complex 2D UI; it establishes no complete UI/EUI, layout, full Spine, migration, phone energy/performance or native SDK/PC acceptance.
65
+ <!-- NS1-DOC-0.41.0-END -->
66
+
67
+ <!-- BW1-DOC-0.40.0-BEGIN -->
68
+ ## Owned binary authoring
69
+
70
+ The root exposes the original `ByteWriter` and frozen `BYTE_WRITER_LIMITS`: fixed capacity, strict integer domains and native IEEE floating conversion. `toUint8Array()` copies only the committed prefix; `Scope.use(writer)` uses existing lifetime ownership. ByteOrder stays type-only and optional host entries add no writer. See the [contract](../../knowledge-base/en/docs/byte-writer-bw1-contract.md) and [evidence](../../knowledge-base/en/docs/byte-writer-bw1-evidence.md) for the complete scope and separate acceptance stages. Package version, experimental status and npm publication conventions remain unchanged.
71
+ <!-- BW1-DOC-0.40.0-END -->
@@ -0,0 +1,71 @@
1
+ # @egret/runtime
2
+
3
+ [English](README.md) | 简体中文
4
+
5
+ 白鹭实验性逻辑包,仅依赖 `@egret/contracts`。接收事件描述符、同步清理值及 Engine 注入的窄生命周期端口,提供取消、Scope、显示树、同步派发和 CPU 资源获取/租约,维持 Scope 所有权、对象与 Engine 绑定、父子关系及事件状态。
6
+
7
+ ## 工程预览 0.52.0 — 显示锚点偏移
8
+
9
+ 现有显示类继承有限 number 属性 `anchorOffsetX` 与 `anchorOffsetY`,默认 +0。指定枢轴使缩放/旋转在坐标、逻辑边界、裁剪、显式命中及帧捕获中保持一致,并保留原零偏移字节。阅读[当前契约](../../knowledge-base/Cns/docs/显示锚点偏移契约.md)和[有限证据](../../knowledge-base/Cns/docs/显示锚点偏移证据.md)。
10
+
11
+ **以下模块旧说明保留早于 0.52.0 的原截止点。** 其中早先的待完成表述限定原版本;当前接受范围由所链接的新证据确定。完整 EUI/布局和完整 Spine 仍为 OPEN。
12
+
13
+ DisplayObjectContainer.getChildIndex(child: DisplayObject): number 只读查询精确当前直接子节点,以 O(n) 扫描私有真实顺序,不建立列表快照/缓存,不修改树、转移 owner、操作资源或调用显示回调。Sprite/Stage 继承,根值/类型、子入口、依赖及协议不变。 阅读 [0.50 契约](../../knowledge-base/Cns/docs/容器子节点索引契约.md).
14
+
15
+ `DisplayObjectContainer.removeChildren(): void` 清空显示层,同时保留节点、后代、资源及清理所有者。它认证真实接收者,空容器也先检查 Engine 再检查接收者生命周期,在全部直接边校验后无调用者 hook 提交;Sprite 和 Stage 继承方法,根值/类型、规格、依赖和协议不变。 阅读 [0.49 契约](../../knowledge-base/Cns/docs/容器清空子节点契约.md).
16
+
17
+ 工程预览 0.48.0 在 Runtime/Engine 根入口新增 `NineSliceBitmap` 及擦除类型 `NineSliceBitmapOptions`,借用真实 Texture 租约调整固定边框 NS1 内容;两个共享宿主均可绘制。阅读[契约](../../knowledge-base/Cns/docs/九宫格位图契约.md)及[有限证据](../../knowledge-base/Cns/docs/九宫格位图证据.md)。
18
+
19
+ 继承的 `getBounds` 读取权威接收者局部内容,提供类型专用 `BoundsQueryOptions`、显式节点/图元预算及全新冻结结果,见[边界契约](../../knowledge-base/Cns/docs/显示内容边界契约.md)。
20
+
21
+ 继承的显示坐标查询使用真实显示状态、有界祖先/生命周期检查及可选的 `CoordinateQueryOptions`。 阅读[坐标契约](../../knowledge-base/Cns/docs/显示坐标查询契约.md)。
22
+
23
+ ## 所有权与清理
24
+
25
+ `EngineContext`、`createScope` 与 `createStage` 供引擎内部装配,公共门面不导出。Engine 创建 Scope、Stage 和 AssetManager;资源类型与引用由工厂创建并在运行时核查。共享获取任务和独立租约保持分离,见[资源合同](../../knowledge-base/Cns/docs/资源核心合同.md)。
26
+
27
+ Scope 登记处理同值递归、用户回调后的状态复核、关闭期间迟到值及所有权冲突。内部挂载和终结保持实际树状态,不隐式调用公共 `removeChild` 重载;当前合同没有 mount/remove 通知。清理失败逐项记录,继续处理其余监听和子树;递归终结遵守发起根的 owner 边界。
28
+
29
+ signal 登记失败撤回订阅并尝试 adapter 回滚。同步事件 handler 返回 Promise 时同步拒绝,并观察其拒绝。
30
+
31
+ ## 显示与帧状态
32
+
33
+ 内部可视状态和迭代帧提取保持权威树顺序;公共 getter 不作为帧事实来源。Graphics 归其 Sprite 所有。裁剪与矩形值复制并冻结,后续修改不能改变旧帧。离树但仍绑定的对象同样遵守引擎 closing 限制。
34
+
35
+ 通过引擎门面,`DisplayObject` 提供 `x`、`y`、`scaleX`、`scaleY`、`rotation`、`alpha`、`visible` 与 `clipRect`;`Sprite.graphics` 拥有矩形填充。`Engine.captureSharedFrame`/`renderSharedFrame` 捕获/提交不可变 `SharedRenderFrame2D`。浏览器宿主是独立的 `@egret/engine/webgpu` 与 `@egret/engine/webgl2` 入口,根入口保持无 DOM。见[共享渲染 Profile 契约](../../knowledge-base/Cns/docs/shared-render-profile-contract.md);自动帧调度不属于该契约。
36
+
37
+ ## 验证与范围
38
+
39
+ 行为测试使用公共 engine 构建入口。在仓库根运行 `node tools/verify.mjs`。设计与绑定版本的证据见[知识库](../../knowledge-base/Cns/README.md)及[显示与帧实现记录](../../knowledge-base/Cns/docs/显示与帧执行实现记录.md),归属见[来源记录](../../source-origin.json)。
40
+
41
+ 接口保持实验性质。完整文字、纹理、动画、UI 与 3D 执行、Native 支持、目标设备性能、编辑器、Agent 服务及完整迁移须分别验收。包版本 `0.0.0` 与 `private: true` 保持不变;本指南不产生 npm 发布。第一方代码与本文采用 [Apache-2.0](../../LICENSE)。
42
+
43
+ ## 显式序列动画
44
+
45
+ `createSequenceClip` 拥有已校验图集时序;`SequencePlayer` 把调用方提供的绝对秒数应用于一个 Bitmap 与确切借用租约。构造不改变裁剪,销毁不释放调用方资源,不包含自动调度器。见[契约与验收范围](../../knowledge-base/Cns/docs/显式时间序列播放器契约.md),以及公共 `examples/sequence-player` / `tools/sequence-player` 指南。
46
+
47
+ ## 自有二进制读取
48
+
49
+ 根入口导出 `ByteReader` 与冻结的 `BYTE_READER_LIMITS`,以及仅类型 `ByteOrder`。读取器复制符合条件的固定普通 Uint8Array 载荷,默认 bigEndian,提供有界原子标量/复制读取;返回字节是独立副本,释放清除自有引用。既有 Scope 可通过可释放对象形状管理读取器。阅读 [BR1 契约](../../knowledge-base/Cns/docs/字节读取器BR1契约.md)与[已有验证范围](../../knowledge-base/Cns/docs/字节读取器BR1证据.md)。不承诺二进制格式、文字编码或旧 ByteArray 兼容;本准备截止点的 Main 集成与公开门禁仍待完成。
50
+
51
+ <!-- NS1-DOC-0.41.0-BEGIN -->
52
+ ## 工程预览 0.41.0 — 九宫格拉伸几何 NS1
53
+
54
+ **S094 / V045。有限 CPU、类型、策略和浏览器结果已接受;完整发布门禁与交付仍为 PENDING。** 固定边框的拉伸网格复用现有 Mesh2D 纹理租约,调整尺寸时仅替换几何。运行时/引擎根入口提供一个工厂与两个只读类型,保留原有自有几何身份。
55
+
56
+ 实际 CPU 27/27 项通过,其中 11 个 NS 组、6 个 Mesh 组及包含嵌套用例的 10 项几何检查。正例类型诊断为 0;两组刻意负例实际为 41/35 条,共 76 条精确位置记录。严格类型门禁与策略检查退出码为 0;指定策略对照 13/13 通过。实际浏览器完成 2 帧和 96 次颜色通道比较,并验证资源清理;具体环境与范围见证据。
57
+
58
+ 原始 NSP09 的 13/12/1 失败与有限测试输入修正分别保留。
59
+
60
+ 0.40.0 ByteWriter 已通过 [PR #27](https://github.com/cnedwin/Egret_rebuild/pull/27) 合并;已回读 Main `8e1509878252cc2a9295fcc56d7597877d023c85` 与 tree `ca1f2f176713e388e09016ae22d610c5c1b95201`。必要推送门禁退出码为 0,公开校验 63 项、核心校验 2724 项。远端状态/检查运行数均为零,不能据此声明远端 CI PASS。较早的 PENDING 截止点和失败记录继续保留。
61
+
62
+ [契约](../../knowledge-base/Cns/docs/九宫格几何NS1契约.md) / [证据](../../knowledge-base/Cns/docs/九宫格几何NS1证据.md)。
63
+
64
+ 这是复杂 2D UI 的有限几何增量,不构成完整 UI/EUI、布局、完整 Spine、迁移、手机能耗/性能或原生 SDK/PC 验收。
65
+ <!-- NS1-DOC-0.41.0-END -->
66
+
67
+ <!-- BW1-DOC-0.40.0-BEGIN -->
68
+ ## 自有二进制写入
69
+
70
+ 根入口提供同一个 `ByteWriter` 与冻结的 `BYTE_WRITER_LIMITS`;容量固定,整数严格校验,浮点遵循原生 IEEE 转换。`toUint8Array()` 只复制已提交前缀,`Scope.use(writer)` 使用原有生命周期。ByteOrder 保持纯类型,可选宿主入口不新增写入器。完整范围与分阶段结果见[契约](../../knowledge-base/Cns/docs/字节写入器BW1契约.md)与[证据](../../knowledge-base/Cns/docs/字节写入器BW1证据.md)。包版本、实验性状态和 npm 发布约定不变。
71
+ <!-- BW1-DOC-0.40.0-END -->
@@ -0,0 +1,23 @@
1
+ import type { EngineContext } from "./ownership.js";
2
+ declare const LEASE_VALUE: unique symbol;
3
+ export declare let createAssetLease: <T>(engine: EngineContext, leaseId: number, generation: number, read: () => T, release: () => void) => AssetLease<T>;
4
+ /** One independently revocable CPU-value borrow, bound to its originating Engine. */
5
+ export declare class AssetLease<T> {
6
+ readonly [LEASE_VALUE]?: (value: T) => T;
7
+ readonly leaseId: number;
8
+ readonly resourceGeneration: number;
9
+ private constructor();
10
+ get value(): T;
11
+ /** Revoke before invoking the manager so disposer reentry sees a released lease. */
12
+ release(): void;
13
+ }
14
+ /** Manager shutdown revokes all leases before any external cleanup callback. */
15
+ export declare function revokeAssetLease(lease: AssetLease<unknown>): void;
16
+ /** Install one cache-owned, counter-only retirement observer without changing the lease. */
17
+ export declare function observeAssetLeaseRetirement(lease: unknown, onRetired: () => void): boolean;
18
+ /** Runtime-private identity guard; proxies and lookalikes cannot supply entitlement. */
19
+ export declare function isAssetLease(value: unknown): value is AssetLease<unknown>;
20
+ /** Read the manager-owned value, without overridable getters or descriptor callbacks. */
21
+ export declare function readAssetLeaseValue(value: unknown): unknown;
22
+ export {};
23
+ //# sourceMappingURL=AssetLease.d.ts.map
@@ -0,0 +1,69 @@
1
+ import { EgretError } from "./EgretError.js";
2
+ import { commitBinding } from "./ownership.js";
3
+ const CREATION_TOKEN = Symbol("egret.assetLeaseFactory");
4
+ const states = new WeakMap();
5
+ export let createAssetLease;
6
+ /** One independently revocable CPU-value borrow, bound to its originating Engine. */
7
+ export class AssetLease {
8
+ leaseId;
9
+ resourceGeneration;
10
+ constructor(engine, leaseId, generation, read, release, token) {
11
+ if (token !== CREATION_TOKEN)
12
+ throw new EgretError("ASSET_LEASE_FACTORY_REQUIRED");
13
+ this.leaseId = leaseId;
14
+ this.resourceGeneration = generation;
15
+ states.set(this, { active: true, read, release, onRetired: undefined });
16
+ commitBinding([this], engine);
17
+ Object.freeze(this);
18
+ }
19
+ static {
20
+ createAssetLease = (engine, leaseId, generation, read, release) => new AssetLease(engine, leaseId, generation, read, release, CREATION_TOKEN);
21
+ }
22
+ get value() {
23
+ const state = states.get(this);
24
+ if (state === undefined || !state.active)
25
+ throw new EgretError("ASSET_LEASE_RELEASED");
26
+ return state.read();
27
+ }
28
+ /** Revoke before invoking the manager so disposer reentry sees a released lease. */
29
+ release() {
30
+ const state = states.get(this);
31
+ if (state === undefined || !state.active)
32
+ return;
33
+ state.active = false;
34
+ const onRetired = state.onRetired;
35
+ state.onRetired = undefined;
36
+ onRetired?.();
37
+ state.release();
38
+ }
39
+ }
40
+ /** Manager shutdown revokes all leases before any external cleanup callback. */
41
+ export function revokeAssetLease(lease) {
42
+ const state = states.get(lease);
43
+ if (state === undefined || !state.active)
44
+ return;
45
+ state.active = false;
46
+ const onRetired = state.onRetired;
47
+ state.onRetired = undefined;
48
+ onRetired?.();
49
+ }
50
+ /** Install one cache-owned, counter-only retirement observer without changing the lease. */
51
+ export function observeAssetLeaseRetirement(lease, onRetired) {
52
+ const state = states.get(lease);
53
+ if (state === undefined || !state.active || state.onRetired !== undefined)
54
+ return false;
55
+ state.onRetired = onRetired;
56
+ return true;
57
+ }
58
+ /** Runtime-private identity guard; proxies and lookalikes cannot supply entitlement. */
59
+ export function isAssetLease(value) {
60
+ return states.has(value);
61
+ }
62
+ /** Read the manager-owned value, without overridable getters or descriptor callbacks. */
63
+ export function readAssetLeaseValue(value) {
64
+ const state = states.get(value);
65
+ if (state === undefined || !state.active)
66
+ throw new EgretError("ASSET_LEASE_RELEASED");
67
+ return state.read();
68
+ }
69
+ //# sourceMappingURL=AssetLease.js.map
@@ -0,0 +1,56 @@
1
+ import type { CancellationSignal } from "@egret/contracts";
2
+ import { AssetLease } from "./AssetLease.js";
3
+ import type { AssetRef, AssetType } from "./AssetRef.js";
4
+ import type { EngineContext } from "./ownership.js";
5
+ import type { AssetLoadContext } from "./assetState.js";
6
+ export type { AssetLoadContext } from "./assetState.js";
7
+ export interface AssetProvider<T> {
8
+ load(ref: AssetRef<T>, context: AssetLoadContext): Promise<T>;
9
+ dispose(value: T): void;
10
+ }
11
+ export interface AssetAcquireOptions {
12
+ readonly signal?: CancellationSignal;
13
+ }
14
+ export declare let createAssetManager: (engine: EngineContext) => AssetManager;
15
+ /** CPU acquisition only: demand retains values; completed unused values are evicted. */
16
+ export declare class AssetManager {
17
+ #private;
18
+ private closed;
19
+ private taskId;
20
+ private leaseId;
21
+ private readonly providers;
22
+ private readonly identities;
23
+ private readonly current;
24
+ private readonly entries;
25
+ private constructor();
26
+ private assertOpen;
27
+ /** Snapshot method identity and receiver once, including getter reentry checks. */
28
+ register<T>(type: AssetType<T>, provider: AssetProvider<NoInfer<T>>): void;
29
+ /** The executor commits an entry and its first waiter before any loader callback. */
30
+ acquire<T>(ref: AssetRef<T>, options?: AssetAcquireOptions): Promise<AssetLease<T>>;
31
+ private identityFor;
32
+ /** Authenticate all positions without reserving identity or creating demand. */
33
+ private admitGroupRefs;
34
+ /** Lease identity, affinity and one cleanup owner are checked before publication. */
35
+ private claimGroupLease;
36
+ /** Invalidation changes future routing, while old demand keeps its own entry. */
37
+ invalidate<T>(ref: AssetRef<T>): void;
38
+ private installSignal;
39
+ /** Mark local subscription inert before adapter removal; throws retain diagnostics. */
40
+ private detach;
41
+ private start;
42
+ private receive;
43
+ private deliver;
44
+ private failWaiter;
45
+ private failEntry;
46
+ /** Remove only this entry: old-generation cleanup cannot delete its replacement. */
47
+ private markTerminal;
48
+ private isTerminal;
49
+ private retireUnused;
50
+ /** One attempted disposal per successful result, even if the disposer throws. */
51
+ private cleanup;
52
+ private diagnose;
53
+ /** Close the gate and revoke every local demand before the first external hook. */
54
+ dispose(): void;
55
+ }
56
+ //# sourceMappingURL=AssetManager.d.ts.map