@egret/runtime 0.0.0-stage → 7.0.2

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 (157) 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 +58 -0
  8. package/dist/AssetManager.js +451 -0
  9. package/dist/AssetRef.d.ts +21 -0
  10. package/dist/AssetRef.js +33 -0
  11. package/dist/Bitmap.d.ts +40 -0
  12. package/dist/Bitmap.js +545 -0
  13. package/dist/ByteReader.d.ts +32 -0
  14. package/dist/ByteReader.js +178 -0
  15. package/dist/ByteWriter.d.ts +30 -0
  16. package/dist/ByteWriter.js +181 -0
  17. package/dist/CancellationController.d.ts +10 -0
  18. package/dist/CancellationController.js +66 -0
  19. package/dist/DisplayObject.d.ts +97 -0
  20. package/dist/DisplayObject.js +366 -0
  21. package/dist/DisplayObjectContainer.d.ts +28 -0
  22. package/dist/DisplayObjectContainer.js +226 -0
  23. package/dist/EgretError.d.ts +12 -0
  24. package/dist/EgretError.js +36 -0
  25. package/dist/Event.d.ts +47 -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 +117 -0
  30. package/dist/Graphics.js +548 -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 +19 -0
  36. package/dist/NineSliceGeometry2D.js +126 -0
  37. package/dist/Scope.d.ts +19 -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 +30 -0
  46. package/dist/Texture.js +178 -0
  47. package/dist/assetManagerOwnerState.d.ts +36 -0
  48. package/dist/assetManagerOwnerState.js +115 -0
  49. package/dist/assetState.d.ts +45 -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 +76 -0
  74. package/dist/displayVisualState.js +141 -0
  75. package/dist/errorHelp.d.ts +15 -0
  76. package/dist/errorHelp.js +435 -0
  77. package/dist/errorHelpZh.d.ts +5 -0
  78. package/dist/errorHelpZh.js +342 -0
  79. package/dist/geometry.d.ts +173 -0
  80. package/dist/geometry.js +311 -0
  81. package/dist/graphicsFill.d.ts +37 -0
  82. package/dist/graphicsFill.js +302 -0
  83. package/dist/graphicsShape.d.ts +170 -0
  84. package/dist/graphicsShape.js +961 -0
  85. package/dist/index.d.ts +53 -0
  86. package/dist/index.js +31 -0
  87. package/dist/input/PointerRouter.d.ts +4 -0
  88. package/dist/input/PointerRouter.js +453 -0
  89. package/dist/input/index.d.ts +3 -0
  90. package/dist/input/index.js +3 -0
  91. package/dist/input/types.d.ts +64 -0
  92. package/dist/input/types.js +3 -0
  93. package/dist/meshCaptureSnapshot.d.ts +5 -0
  94. package/dist/meshCaptureSnapshot.js +13 -0
  95. package/dist/meshDisplayState.d.ts +18 -0
  96. package/dist/meshDisplayState.js +21 -0
  97. package/dist/ownership.d.ts +75 -0
  98. package/dist/ownership.js +157 -0
  99. package/dist/paragraph/Paragraph.d.ts +13 -0
  100. package/dist/paragraph/Paragraph.js +193 -0
  101. package/dist/paragraph/ParagraphCache.d.ts +5 -0
  102. package/dist/paragraph/ParagraphCache.js +354 -0
  103. package/dist/paragraph/geometry.d.ts +4 -0
  104. package/dist/paragraph/geometry.js +180 -0
  105. package/dist/paragraph/index.d.ts +3 -0
  106. package/dist/paragraph/index.js +3 -0
  107. package/dist/paragraph/request.d.ts +6 -0
  108. package/dist/paragraph/request.js +191 -0
  109. package/dist/paragraph/types.d.ts +183 -0
  110. package/dist/paragraph/types.js +2 -0
  111. package/dist/preparedDisplaySubtree.d.ts +7 -0
  112. package/dist/preparedDisplaySubtree.js +205 -0
  113. package/dist/renderEffect.d.ts +57 -0
  114. package/dist/renderEffect.js +109 -0
  115. package/dist/sequenceClip.d.ts +48 -0
  116. package/dist/sequenceClip.js +197 -0
  117. package/dist/sharedFrameCapture.d.ts +24 -0
  118. package/dist/sharedFrameCapture.js +1128 -0
  119. package/dist/spriteSheet.d.ts +34 -0
  120. package/dist/spriteSheet.js +321 -0
  121. package/dist/srgbBytes.d.ts +3 -0
  122. package/dist/srgbBytes.js +64 -0
  123. package/dist/text/TextField.d.ts +13 -0
  124. package/dist/text/TextField.js +261 -0
  125. package/dist/text/TextRasterCache.d.ts +5 -0
  126. package/dist/text/TextRasterCache.js +1191 -0
  127. package/dist/text/budget.d.ts +51 -0
  128. package/dist/text/budget.js +116 -0
  129. package/dist/text/index.d.ts +4 -0
  130. package/dist/text/index.js +3 -0
  131. package/dist/text/plan.d.ts +16 -0
  132. package/dist/text/plan.js +238 -0
  133. package/dist/text/request.d.ts +44 -0
  134. package/dist/text/request.js +303 -0
  135. package/dist/text/types.d.ts +179 -0
  136. package/dist/text/types.js +2 -0
  137. package/dist/textDisplayState.d.ts +21 -0
  138. package/dist/textDisplayState.js +27 -0
  139. package/dist/ui/displayCommit.d.ts +43 -0
  140. package/dist/ui/displayCommit.js +384 -0
  141. package/dist/ui/editing.d.ts +3 -0
  142. package/dist/ui/editing.js +3 -0
  143. package/dist/ui/heightIndex.d.ts +35 -0
  144. package/dist/ui/heightIndex.js +295 -0
  145. package/dist/ui/index.d.ts +6 -0
  146. package/dist/ui/index.js +6 -0
  147. package/dist/ui/layout.d.ts +9 -0
  148. package/dist/ui/layout.js +349 -0
  149. package/dist/ui/managedState.d.ts +12 -0
  150. package/dist/ui/managedState.js +44 -0
  151. package/dist/ui/textEditState.d.ts +4 -0
  152. package/dist/ui/textEditState.js +206 -0
  153. package/dist/ui/textEditTypes.d.ts +48 -0
  154. package/dist/ui/textEditTypes.js +2 -0
  155. package/dist/ui/types.d.ts +99 -0
  156. package/dist/ui/types.js +2 -0
  157. package/package.json +44 -4
package/dist/Bitmap.js ADDED
@@ -0,0 +1,545 @@
1
+ import { captureAtlasFrameLayout, copyAtlasFrameLayout } from "./atlasFrameLayout.js";
2
+ import { isAssetLease, readAssetLeaseValue } from "./AssetLease.js";
3
+ import { AssetLease } from "./AssetLease.js";
4
+ import { DisplayObject } from "./DisplayObject.js";
5
+ import { hasBitmapState, readBitmapState, writeBitmapState } from "./bitmapDisplayState.js";
6
+ import { assertLive, isStageRoot, isTerminated } from "./displayTreeState.js";
7
+ import { collectPreparedSharedFrameContent } from "./sharedFrameCapture.js";
8
+ import { EgretError } from "./EgretError.js";
9
+ import { claimOwner, ownerOf, commitBinding, engineOf } from "./ownership.js";
10
+ import { isTexture, readTextureImage, readTextureSnapshot } from "./Texture.js";
11
+ /** Internal-only original Bitmap operations; neither public root forwards this port. */
12
+ export let spriteSheetBitmapOperations;
13
+ const mutations = new WeakSet();
14
+ const freezeAtlasState = Object.freeze;
15
+ const resourceTargetOperations = new WeakMap();
16
+ const freezeResourceOperations = Object.freeze;
17
+ const releaseResourceLease = AssetLease.prototype.release;
18
+ const applyResourceOperation = Reflect.apply;
19
+ /** Exact context and opaque prepared provenance stay inside this runtime module. */
20
+ function operationsFor(context) {
21
+ let operations = resourceTargetOperations.get(context);
22
+ if (operations !== undefined)
23
+ return operations;
24
+ const preparedStates = new WeakMap();
25
+ const batchCaptures = new WeakMap();
26
+ const batchPreparedStates = new WeakMap();
27
+ const batchPublications = new WeakMap();
28
+ const affinity = (value) => {
29
+ if (engineOf(value) !== context)
30
+ throw new EgretError("ENGINE_MISMATCH");
31
+ };
32
+ const batchAffinity = (targets) => {
33
+ for (let index = 0; index < targets.length; index++) {
34
+ affinity(targets[index]);
35
+ assertBitmap(targets[index]);
36
+ }
37
+ };
38
+ const batchLife = (targets) => {
39
+ context.assertOpen();
40
+ for (let index = 0; index < targets.length; index++)
41
+ assertLive(targets[index]);
42
+ };
43
+ const capturedBatch = (captured) => {
44
+ const entry = batchCaptures.get(captured);
45
+ if (entry === undefined)
46
+ throw new EgretError("BITMAP_RESOURCE_PREPARED_INVALID");
47
+ return entry;
48
+ };
49
+ const expectedBatch = (entry) => {
50
+ // Complete the entire token pass before reading even the first entitlement.
51
+ for (let index = 0; index < entry.targets.length; index++) {
52
+ if (readBitmapState(entry.targets[index]) !== entry.expected[index]) {
53
+ throw new EgretError("BITMAP_RESOURCE_BINDING_CHANGED");
54
+ }
55
+ }
56
+ };
57
+ const batchImage = (lease) => {
58
+ if (!isAssetLease(lease))
59
+ throw new EgretError("BITMAP_LEASE_INVALID");
60
+ affinity(lease);
61
+ return readBitmapImage(lease);
62
+ };
63
+ const oldBatchImages = (entry) => {
64
+ for (let index = 0; index < entry.expected.length; index++)
65
+ batchImage(entry.expected[index].lease);
66
+ };
67
+ const liveBinding = (bitmap, expected) => {
68
+ affinity(bitmap);
69
+ const state = readBitmapBinding(bitmap);
70
+ // A changed binding wins before any external entitlement revocation.
71
+ if (expected !== undefined && state !== expected)
72
+ throw new EgretError("BITMAP_RESOURCE_BINDING_CHANGED");
73
+ if (state === undefined)
74
+ throw new EgretError("BITMAP_RESOURCE_TEXTURE_REQUIRED");
75
+ readBitmapImage(state.lease);
76
+ return state;
77
+ };
78
+ operations = freezeResourceOperations({
79
+ capture(bitmap, expected) {
80
+ return liveBinding(bitmap, expected);
81
+ },
82
+ prepare(bitmap, lease) {
83
+ affinity(bitmap);
84
+ affinity(lease);
85
+ liveBinding(bitmap);
86
+ const snapshot = readBitmapImage(lease);
87
+ // Use the captured intrinsic; no late public setter or freeze callback.
88
+ const state = freezeResourceOperations({
89
+ lease,
90
+ sourceRect: snapshot.sourceRect,
91
+ viewRegion: snapshot.viewRegion,
92
+ width: snapshot.viewRegion?.logicalWidth ?? snapshot.sourceRect.width,
93
+ height: snapshot.viewRegion?.logicalHeight ?? snapshot.sourceRect.height
94
+ });
95
+ preparedStates.set(state, { bitmap, state });
96
+ return state;
97
+ },
98
+ commit(bitmap, expected, prepared) {
99
+ affinity(bitmap);
100
+ assertBitmap(bitmap);
101
+ const entry = preparedStates.get(prepared);
102
+ if (entry === undefined || entry.bitmap !== bitmap)
103
+ throw new EgretError("BITMAP_RESOURCE_PREPARED_INVALID");
104
+ affinity(entry.state.lease);
105
+ assertLive(bitmap);
106
+ context.assertOpen();
107
+ if (mutations.has(bitmap))
108
+ throw new EgretError("BITMAP_MUTATION_REENTRANT");
109
+ const current = readBitmapState(bitmap);
110
+ if (current !== expected)
111
+ throw new EgretError("BITMAP_RESOURCE_BINDING_CHANGED");
112
+ // Both entitlements are fresh even when expected state identity is unchanged.
113
+ if (current === undefined)
114
+ throw new EgretError("BITMAP_RESOURCE_TEXTURE_REQUIRED");
115
+ readBitmapImage(current.lease);
116
+ readBitmapImage(entry.state.lease);
117
+ preparedStates.delete(prepared);
118
+ writeBitmapState(bitmap, entry.state);
119
+ },
120
+ clearIfCurrent(bitmap, expected) {
121
+ affinity(bitmap);
122
+ assertBitmap(bitmap);
123
+ const current = readBitmapState(bitmap);
124
+ if (current === undefined || current !== expected)
125
+ return false;
126
+ writeBitmapState(bitmap, undefined);
127
+ return true;
128
+ },
129
+ claim(bitmap, lease, owner) {
130
+ affinity(bitmap);
131
+ affinity(lease);
132
+ assertBitmap(bitmap);
133
+ assertLive(bitmap);
134
+ context.assertOpen();
135
+ if (!isAssetLease(lease) || ownerOf(lease) !== undefined)
136
+ throw new EgretError("BITMAP_RESOURCE_LEASE_INVALID");
137
+ readAssetLeaseValue(lease);
138
+ claimOwner(lease, owner);
139
+ },
140
+ release(lease) {
141
+ affinity(lease);
142
+ if (!isAssetLease(lease))
143
+ throw new EgretError("BITMAP_RESOURCE_LEASE_INVALID");
144
+ applyResourceOperation(releaseResourceLease, lease, []);
145
+ },
146
+ captureBatch(targets) {
147
+ if (!Array.isArray(targets) || targets.length < 1 || targets.length > 128) {
148
+ throw new EgretError("BITMAP_BINDING_TARGETS_INVALID");
149
+ }
150
+ const copied = [], seen = new Set();
151
+ for (let index = 0; index < targets.length; index++) {
152
+ const bitmap = targets[index];
153
+ affinity(bitmap);
154
+ assertBitmap(bitmap);
155
+ if (seen.has(bitmap))
156
+ throw new EgretError("BITMAP_BINDING_TARGETS_INVALID");
157
+ seen.add(bitmap);
158
+ copied.push(bitmap);
159
+ }
160
+ batchLife(copied);
161
+ const expected = [];
162
+ for (let index = 0; index < copied.length; index++) {
163
+ const state = readBitmapState(copied[index]);
164
+ if (state === undefined)
165
+ throw new EgretError("BITMAP_RESOURCE_TEXTURE_REQUIRED");
166
+ expected.push(state);
167
+ }
168
+ for (let index = 0; index < expected.length; index++)
169
+ batchImage(expected[index].lease);
170
+ const captured = freezeResourceOperations({});
171
+ batchCaptures.set(captured, freezeResourceOperations({
172
+ targets: freezeResourceOperations(copied),
173
+ expected: freezeResourceOperations(expected)
174
+ }));
175
+ return captured;
176
+ },
177
+ prepareBatch(captured, members) {
178
+ const entry = capturedBatch(captured);
179
+ batchAffinity(entry.targets);
180
+ batchLife(entry.targets);
181
+ if (!Array.isArray(members) || members.length !== entry.targets.length) {
182
+ throw new EgretError("BITMAP_BINDING_MEMBERS_INVALID");
183
+ }
184
+ const leases = [];
185
+ for (let index = 0; index < entry.targets.length; index++)
186
+ leases.push(members[index]);
187
+ batchLife(entry.targets);
188
+ expectedBatch(entry);
189
+ oldBatchImages(entry);
190
+ const snapshots = [];
191
+ for (let index = 0; index < leases.length; index++)
192
+ snapshots.push(batchImage(leases[index]));
193
+ const states = [];
194
+ for (let index = 0; index < snapshots.length; index++) {
195
+ const snapshot = snapshots[index];
196
+ states.push(freezeResourceOperations({
197
+ lease: leases[index],
198
+ sourceRect: snapshot.sourceRect,
199
+ viewRegion: snapshot.viewRegion,
200
+ width: snapshot.viewRegion?.logicalWidth ?? snapshot.sourceRect.width,
201
+ height: snapshot.viewRegion?.logicalHeight ?? snapshot.sourceRect.height
202
+ }));
203
+ }
204
+ const prepared = freezeResourceOperations({});
205
+ batchPreparedStates.set(prepared, freezeResourceOperations({ captured, states: freezeResourceOperations(states) }));
206
+ return prepared;
207
+ },
208
+ commitBatch(captured, prepared) {
209
+ const entry = capturedBatch(captured);
210
+ batchAffinity(entry.targets);
211
+ const candidate = batchPreparedStates.get(prepared);
212
+ if (candidate === undefined || candidate.captured !== captured)
213
+ throw new EgretError("BITMAP_RESOURCE_PREPARED_INVALID");
214
+ batchLife(entry.targets);
215
+ for (let index = 0; index < entry.targets.length; index++) {
216
+ if (mutations.has(entry.targets[index]))
217
+ throw new EgretError("BITMAP_MUTATION_REENTRANT");
218
+ }
219
+ expectedBatch(entry);
220
+ oldBatchImages(entry);
221
+ for (let index = 0; index < candidate.states.length; index++)
222
+ batchImage(candidate.states[index].lease);
223
+ // Allocate publication/provenance before consuming the plan or writing any target.
224
+ const publication = freezeResourceOperations({});
225
+ batchPublications.set(publication, { targets: entry.targets, states: candidate.states, active: true });
226
+ batchPreparedStates.delete(prepared);
227
+ for (let index = 0; index < entry.targets.length; index++)
228
+ writeBitmapState(entry.targets[index], candidate.states[index]);
229
+ return publication;
230
+ },
231
+ capturePreparedSharedContent(stage, captured, prepared) {
232
+ const entry = capturedBatch(captured), candidate = batchPreparedStates.get(prepared);
233
+ if (candidate === undefined || candidate.captured !== captured)
234
+ throw new EgretError("BITMAP_RESOURCE_PREPARED_INVALID");
235
+ const validate = () => {
236
+ if (batchCaptures.get(captured) !== entry || batchPreparedStates.get(prepared) !== candidate) {
237
+ throw new EgretError("BITMAP_RESOURCE_PREPARED_INVALID");
238
+ }
239
+ if (!isStageRoot(stage))
240
+ throw new EgretError("FRAME_STAGE_INVALID");
241
+ affinity(stage);
242
+ batchAffinity(entry.targets);
243
+ batchLife(entry.targets);
244
+ for (let index = 0; index < entry.targets.length; index++) {
245
+ if (mutations.has(entry.targets[index]))
246
+ throw new EgretError("BITMAP_MUTATION_REENTRANT");
247
+ }
248
+ expectedBatch(entry);
249
+ oldBatchImages(entry);
250
+ for (let index = 0; index < candidate.states.length; index++)
251
+ batchImage(candidate.states[index].lease);
252
+ };
253
+ validate();
254
+ const selected = new Map();
255
+ for (let index = 0; index < entry.targets.length; index++)
256
+ selected.set(entry.targets[index], candidate.states[index]);
257
+ // The completed map never escapes this frozen view or receives another write.
258
+ // Whole states preserve crop, logical dimensions, rotation and atlas metadata.
259
+ const view = freezeResourceOperations({
260
+ read(node) {
261
+ return selected.get(node) ?? readBitmapState(node);
262
+ }
263
+ });
264
+ const content = collectPreparedSharedFrameContent(stage, view);
265
+ validate();
266
+ return content;
267
+ },
268
+ clearBatchIfCurrent(publication) {
269
+ const entry = batchPublications.get(publication);
270
+ if (entry === undefined)
271
+ throw new EgretError("BITMAP_RESOURCE_PREPARED_INVALID");
272
+ batchAffinity(entry.targets);
273
+ if (!entry.active)
274
+ return;
275
+ entry.active = false;
276
+ // Cleanup is valid during closing, after target disposal or lease revocation.
277
+ for (let index = 0; index < entry.targets.length; index++) {
278
+ const target = entry.targets[index];
279
+ if (readBitmapState(target) === entry.states[index])
280
+ writeBitmapState(target, undefined);
281
+ }
282
+ }
283
+ });
284
+ resourceTargetOperations.set(context, operations);
285
+ return operations;
286
+ }
287
+ function assertBitmap(value) {
288
+ if (!hasBitmapState(value))
289
+ throw new EgretError("BITMAP_INVALID");
290
+ }
291
+ function captureState(lease, sourceRect, viewRegion = null) {
292
+ return Object.freeze({
293
+ lease,
294
+ sourceRect,
295
+ viewRegion,
296
+ width: viewRegion?.logicalWidth ?? sourceRect.width,
297
+ height: viewRegion?.logicalHeight ?? sourceRect.height
298
+ });
299
+ }
300
+ /** Shared lease/crop guard starts after the established lifecycle priority. */
301
+ function beginMutation(node) {
302
+ assertBitmap(node);
303
+ assertLive(node);
304
+ const engine = engineOf(node);
305
+ engine.assertOpen();
306
+ if (mutations.has(node))
307
+ throw new EgretError("BITMAP_MUTATION_REENTRANT");
308
+ mutations.add(node);
309
+ return engine;
310
+ }
311
+ /** Terminal side effects win before numeric semantics; no slot resurrection. */
312
+ function revalidateMutation(node, engine, previous) {
313
+ assertLive(node);
314
+ engine.assertOpen();
315
+ if (readBitmapState(node) !== previous)
316
+ throw new EgretError("BITMAP_MUTATION_REENTRANT");
317
+ }
318
+ /** Complete ordered external reads before semantics; preserve every thrown cause. */
319
+ function readRegion(input) {
320
+ if (input === null || typeof input !== "object") {
321
+ throw new EgretError("BITMAP_REGION_INVALID", { cause: new TypeError("Bitmap region must be a record") });
322
+ }
323
+ let x, y, width, height;
324
+ try {
325
+ x = input.x;
326
+ y = input.y;
327
+ width = input.width;
328
+ height = input.height;
329
+ }
330
+ catch (cause) {
331
+ throw new EgretError("BITMAP_REGION_INVALID", { cause });
332
+ }
333
+ // Keep allocation outside the read-fault wrapper and retain no caller record.
334
+ return { x, y, width, height };
335
+ }
336
+ function regionInteger(value, positive) {
337
+ if (typeof value !== "number") {
338
+ throw new EgretError("BITMAP_REGION_INVALID", { cause: new TypeError("Bitmap region fields must be numbers") });
339
+ }
340
+ if (!Number.isSafeInteger(value) || (positive ? value <= 0 : value < 0)) {
341
+ throw new EgretError("BITMAP_REGION_INVALID", { cause: new RangeError("Bitmap region integer range") });
342
+ }
343
+ return value === 0 ? 0 : value;
344
+ }
345
+ /** Absolute crops stay within the authenticated Texture's immutable image view. */
346
+ function copyRegion(base, fields) {
347
+ const x = regionInteger(fields.x, false), y = regionInteger(fields.y, false);
348
+ const width = regionInteger(fields.width, true), height = regionInteger(fields.height, true);
349
+ const right = x + width, bottom = y + height;
350
+ if (!Number.isSafeInteger(right) ||
351
+ !Number.isSafeInteger(bottom) ||
352
+ x < base.x ||
353
+ y < base.y ||
354
+ right > base.x + base.width ||
355
+ bottom > base.y + base.height) {
356
+ throw new EgretError("BITMAP_REGION_INVALID", { cause: new RangeError("Bitmap region exceeds its Texture view") });
357
+ }
358
+ return Object.freeze({ x, y, width, height });
359
+ }
360
+ /** A leaf borrowing one exact lease; engine affinity outlives clearing its slot. */
361
+ export class Bitmap extends DisplayObject {
362
+ constructor(textureLease) {
363
+ super();
364
+ const snapshot = readBitmapImage(textureLease);
365
+ const engine = engineOf(textureLease);
366
+ engine.assertOpen();
367
+ commitBinding([this], engine);
368
+ writeBitmapState(this, captureState(textureLease, snapshot.sourceRect, snapshot.viewRegion));
369
+ // Genuine Engine registration is private; custom runtime contexts own their callback.
370
+ engine.registerBitmapResourceTarget?.(this, operationsFor(engine));
371
+ }
372
+ static {
373
+ // Capture originals before callers can patch this prototype or load a later facade.
374
+ const OriginalBitmap = this;
375
+ const setCrop = Object.getOwnPropertyDescriptor(this.prototype, "sourceRect").set;
376
+ const dispose = this.prototype.dispose;
377
+ const apply = Reflect.apply;
378
+ spriteSheetBitmapOperations = Object.freeze({
379
+ construct: (lease) => new OriginalBitmap(lease),
380
+ setCrop: (bitmap, region) => {
381
+ apply(setCrop, bitmap, [region]);
382
+ },
383
+ dispose: (bitmap) => {
384
+ apply(dispose, bitmap, []);
385
+ }
386
+ });
387
+ }
388
+ get textureLease() {
389
+ assertBitmap(this);
390
+ return readBitmapState(this)?.lease;
391
+ }
392
+ set textureLease(value) {
393
+ const engine = beginMutation(this);
394
+ try {
395
+ const previous = readBitmapState(this);
396
+ if (value === undefined) {
397
+ writeBitmapState(this, undefined);
398
+ return;
399
+ }
400
+ if (!isAssetLease(value))
401
+ throw new EgretError("BITMAP_LEASE_INVALID");
402
+ if (engineOf(value) !== engine)
403
+ throw new EgretError("ENGINE_MISMATCH");
404
+ const snapshot = readBitmapImage(value);
405
+ revalidateMutation(this, engine, previous);
406
+ // Every successful assignment, including the same lease, resets the crop.
407
+ writeBitmapState(this, captureState(value, snapshot.sourceRect, snapshot.viewRegion));
408
+ }
409
+ finally {
410
+ mutations.delete(this);
411
+ }
412
+ }
413
+ /** Cached metadata remains readable without granting live image entitlement. */
414
+ get sourceRect() {
415
+ assertBitmap(this);
416
+ return readBitmapState(this)?.sourceRect;
417
+ }
418
+ set sourceRect(value) {
419
+ const engine = beginMutation(this);
420
+ try {
421
+ const previous = readBitmapState(this);
422
+ if (previous === undefined) {
423
+ if (value !== undefined)
424
+ throw new EgretError("BITMAP_TEXTURE_REQUIRED");
425
+ return;
426
+ }
427
+ // Entitlement and live-view authority precede every external field read.
428
+ const snapshot = readBitmapImage(previous.lease);
429
+ if (snapshot.viewRegion !== null)
430
+ throw new EgretError("TEXTURE_VIEW_REGION_IMMUTABLE");
431
+ if (value === undefined) {
432
+ revalidateMutation(this, engine, previous);
433
+ writeBitmapState(this, captureState(previous.lease, snapshot.sourceRect));
434
+ return;
435
+ }
436
+ const fields = readRegion(value);
437
+ revalidateMutation(this, engine, previous);
438
+ const current = readBitmapImage(previous.lease);
439
+ const sourceRect = copyRegion(current.sourceRect, fields);
440
+ // Crop and natural geometry become observable together, without callbacks.
441
+ writeBitmapState(this, captureState(previous.lease, sourceRect));
442
+ }
443
+ finally {
444
+ mutations.delete(this);
445
+ }
446
+ }
447
+ get naturalWidth() {
448
+ assertBitmap(this);
449
+ return readBitmapState(this)?.width ?? 0;
450
+ }
451
+ get naturalHeight() {
452
+ assertBitmap(this);
453
+ return readBitmapState(this)?.height ?? 0;
454
+ }
455
+ /** Drop the borrow before base cleanup/reentry; the caller still owns the lease. */
456
+ dispose() {
457
+ assertBitmap(this);
458
+ if (isTerminated(this))
459
+ return;
460
+ writeBitmapState(this, undefined);
461
+ super.dispose();
462
+ }
463
+ }
464
+ /** Brand and slot only: geometry may be validated before any lease read. */
465
+ export function bitmapCaptureState(node) {
466
+ return readBitmapState(node);
467
+ }
468
+ /** Internal binding authority; a cleared slot remains distinguishable from retirement. */
469
+ export function readBitmapBinding(node) {
470
+ assertBitmap(node);
471
+ assertLive(node);
472
+ engineOf(node).assertOpen();
473
+ return readBitmapState(node);
474
+ }
475
+ /** Exact entitlement precedes value/live checks; public value getters are not authority. */
476
+ export function readBitmapImage(lease) {
477
+ if (!isAssetLease(lease))
478
+ throw new EgretError("BITMAP_LEASE_INVALID");
479
+ const value = readAssetLeaseValue(lease);
480
+ if (!isTexture(value))
481
+ throw new EgretError("BITMAP_TEXTURE_INVALID");
482
+ return readTextureSnapshot(value);
483
+ }
484
+ /**
485
+ * The image of a lease that `readBitmapImage` has admitted before: the same entitlement, value and live
486
+ * checks with the same refusals, and no record made. A lease stays a lease, so that one check is not repeated.
487
+ */
488
+ export function readBitmapSource(lease) {
489
+ const value = readAssetLeaseValue(lease);
490
+ if (!isTexture(value))
491
+ throw new EgretError("BITMAP_TEXTURE_INVALID");
492
+ return readTextureImage(value);
493
+ }
494
+ /** Private complete-frame bridge; public crop setters deliberately ignore layout. */
495
+ export function applyBitmapAtlasFrame(bitmap, region) {
496
+ const engine = beginMutation(bitmap);
497
+ try {
498
+ const previous = readBitmapState(bitmap);
499
+ if (previous === undefined)
500
+ throw new EgretError("BITMAP_TEXTURE_REQUIRED");
501
+ const initial = readBitmapImage(previous.lease);
502
+ // Internal atlas bridges obey the same immutable-view rule as public crop.
503
+ if (initial.viewRegion !== null)
504
+ throw new EgretError("TEXTURE_VIEW_REGION_IMMUTABLE");
505
+ const fields = readRegion(region);
506
+ const captured = captureAtlasFrameLayout(region, (source, key) => {
507
+ try {
508
+ const present = Object.hasOwn(source, key);
509
+ return { present, value: present ? source[key] : undefined };
510
+ }
511
+ catch (cause) {
512
+ throw new EgretError("BITMAP_REGION_INVALID", { cause });
513
+ }
514
+ }, callback => {
515
+ try {
516
+ return callback();
517
+ }
518
+ catch (cause) {
519
+ throw new EgretError("BITMAP_REGION_INVALID", { cause });
520
+ }
521
+ });
522
+ revalidateMutation(bitmap, engine, previous);
523
+ const snapshot = readBitmapImage(previous.lease);
524
+ const sourceRect = copyRegion(snapshot.sourceRect, fields);
525
+ const layout = copyAtlasFrameLayout(captured, sourceRect.width, sourceRect.height, () => {
526
+ throw new EgretError("BITMAP_REGION_INVALID");
527
+ });
528
+ const next = freezeAtlasState({
529
+ lease: previous.lease,
530
+ sourceRect,
531
+ layout,
532
+ viewRegion: null,
533
+ width: layout.sourceWidth,
534
+ height: layout.sourceHeight
535
+ });
536
+ revalidateMutation(bitmap, engine, previous);
537
+ readBitmapImage(previous.lease);
538
+ // Publish one new token, even for identical crop/layout scalars (ABA protection).
539
+ writeBitmapState(bitmap, next);
540
+ }
541
+ finally {
542
+ mutations.delete(bitmap);
543
+ }
544
+ }
545
+ //# sourceMappingURL=Bitmap.js.map
@@ -0,0 +1,32 @@
1
+ import type { Disposable } from "@egret/contracts";
2
+ /** The order of the bytes of a multi-byte number. */
3
+ export type ByteOrder = "bigEndian" | "littleEndian";
4
+ /** The largest snapshot a ByteReader reads, in bytes. */
5
+ export declare const BYTE_READER_LIMITS: Readonly<{
6
+ readonly maxBytes: 16777216;
7
+ }>;
8
+ /** Read-only owned binary snapshot. Explicit Scope.use() can own its lifetime. */
9
+ export declare class ByteReader implements Disposable {
10
+ private readonly byteReaderBrand;
11
+ constructor(source: Uint8Array<ArrayBuffer>, endian?: ByteOrder);
12
+ get length(): number;
13
+ get position(): number;
14
+ get bytesAvailable(): number;
15
+ get disposed(): boolean;
16
+ get endian(): ByteOrder;
17
+ set endian(value: ByteOrder);
18
+ seek(position: number): void;
19
+ skip(count: number): void;
20
+ readByte(): number;
21
+ readUnsignedByte(): number;
22
+ readShort(): number;
23
+ readUnsignedShort(): number;
24
+ readInt(): number;
25
+ readUnsignedInt(): number;
26
+ readFloat(): number;
27
+ readDouble(): number;
28
+ readBytes(count?: number): Uint8Array<ArrayBuffer>;
29
+ /** Terminal release drops both storage references without claiming zeroization. */
30
+ dispose(): void;
31
+ }
32
+ //# sourceMappingURL=ByteReader.d.ts.map