@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/Scope.js ADDED
@@ -0,0 +1,133 @@
1
+ import { cleanupManagedWrapper } from "./ui/managedState.js";
2
+ import { CancellationController } from "./CancellationController.js";
3
+ import { EgretError } from "./EgretError.js";
4
+ import { claimOwner, commitBinding, engineOf, ownerOf, preflightBinding, validateBinding } from "./ownership.js";
5
+ export let createScope;
6
+ const CREATION_TOKEN = Symbol("egret.scopeFactory");
7
+ const scopes = new WeakSet();
8
+ /** Runtime-private identity for owner-chain lifetime validation. */
9
+ export function isScope(value) {
10
+ return scopes.has(value);
11
+ }
12
+ const activeRegistrations = new WeakSet();
13
+ function cleanup(value) {
14
+ if (cleanupManagedWrapper(value))
15
+ return;
16
+ if ("dispose" in value)
17
+ value.dispose();
18
+ else
19
+ value.release();
20
+ }
21
+ /** Synchronous ownership boundary. Use Engine.createScope() to obtain one. */
22
+ export class Scope {
23
+ #currentState = "open";
24
+ // Runtime-private ownership paths ignore harmless public old-name shadows.
25
+ #values = [];
26
+ #controller;
27
+ #engine;
28
+ #onClosed;
29
+ signal;
30
+ constructor(engine, onClosed, token) {
31
+ if (token !== CREATION_TOKEN)
32
+ throw new EgretError("SCOPE_FACTORY_REQUIRED");
33
+ scopes.add(this);
34
+ this.#engine = engine;
35
+ this.#onClosed = onClosed;
36
+ this.#controller = new CancellationController(diagnostic => {
37
+ this.#engine.captureCleanup(diagnostic.cause);
38
+ this.#engine.report(diagnostic);
39
+ });
40
+ this.signal = this.#controller.signal;
41
+ }
42
+ static {
43
+ createScope = (engine, onClosed) => new Scope(engine, onClosed, CREATION_TOKEN);
44
+ }
45
+ get state() {
46
+ return this.#currentState;
47
+ }
48
+ /** Accept one cleanup owner after callback-free validation of the current tree. */
49
+ use(value) {
50
+ if (activeRegistrations.has(value))
51
+ throw new EgretError("SCOPE_REGISTRATION_ACTIVE");
52
+ activeRegistrations.add(value);
53
+ try {
54
+ const existingOwner = this.#validateAcceptance(value);
55
+ if (existingOwner === this)
56
+ return value;
57
+ preflightBinding(value, this.#engine);
58
+ // Subclass preflight may close a Scope/Engine or mutate the tree. Nothing
59
+ // can invoke user code between the checks below and the ownership commit.
60
+ this.#validateAcceptance(value);
61
+ const binding = validateBinding(value, this.#engine);
62
+ commitBinding(binding, this.#engine);
63
+ claimOwner(value, this);
64
+ this.#values.push(value);
65
+ return value;
66
+ }
67
+ finally {
68
+ activeRegistrations.delete(value);
69
+ }
70
+ }
71
+ #validateAcceptance(value) {
72
+ const existingOwner = ownerOf(value);
73
+ if (existingOwner !== undefined && existingOwner !== this)
74
+ throw new EgretError("OWNERSHIP_CONFLICT");
75
+ const existingEngine = engineOf(value);
76
+ if (existingEngine !== undefined && existingEngine !== this.#engine)
77
+ throw new EgretError("ENGINE_MISMATCH");
78
+ let closedError;
79
+ if (this.#currentState !== "open")
80
+ closedError = new EgretError("SCOPE_CLOSED");
81
+ else {
82
+ try {
83
+ this.#engine.assertOpen();
84
+ }
85
+ catch (cause) {
86
+ closedError = cause instanceof EgretError ? cause : new EgretError("ENGINE_CLOSED", { cause });
87
+ }
88
+ }
89
+ if (closedError !== undefined) {
90
+ const cleanupErrors = [];
91
+ // A late unowned value must be cleaned up; a foreign owner stays authoritative.
92
+ if (existingOwner === undefined) {
93
+ try {
94
+ cleanup(value);
95
+ }
96
+ catch (cause) {
97
+ cleanupErrors.push(cause);
98
+ this.#engine.captureCleanup(cause);
99
+ this.#engine.report({ code: "SCOPE_LATE_CLEANUP_FAILED", phase: "scope", severity: "error", cause });
100
+ }
101
+ }
102
+ throw new EgretError(closedError.code, { cause: closedError.cause, cleanupErrors });
103
+ }
104
+ return existingOwner;
105
+ }
106
+ /** Cancel first, then clean up in reverse acquisition order despite failures. */
107
+ dispose() {
108
+ if (this.#currentState !== "open")
109
+ return;
110
+ this.#currentState = "closing";
111
+ try {
112
+ this.#controller.abort(new EgretError("SCOPE_CLOSED"));
113
+ for (let index = this.#values.length - 1; index >= 0; index--) {
114
+ const value = this.#values[index];
115
+ if (value === undefined)
116
+ continue;
117
+ try {
118
+ cleanup(value);
119
+ }
120
+ catch (cause) {
121
+ this.#engine.captureCleanup(cause);
122
+ this.#engine.report({ code: "SCOPE_CLEANUP_FAILED", phase: "scope", severity: "error", cause });
123
+ }
124
+ }
125
+ }
126
+ finally {
127
+ this.#values.length = 0;
128
+ this.#currentState = "closed";
129
+ this.#onClosed(this);
130
+ }
131
+ }
132
+ }
133
+ //# sourceMappingURL=Scope.js.map
@@ -0,0 +1,12 @@
1
+ import { Bitmap } from './Bitmap.js';
2
+ import type { SequenceClip, SequencePlaybackMode, SequenceSample } from './sequenceClip.js';
3
+ /** Explicit absolute-time selection borrowing a target and its exact current lease. */
4
+ export declare class SequencePlayer {
5
+ constructor(bitmap: Bitmap, clip: SequenceClip, mode?: SequencePlaybackMode);
6
+ applyAt(elapsedSeconds: number): SequenceSample;
7
+ get lastSample(): SequenceSample | undefined;
8
+ get isDisposed(): boolean;
9
+ /** Drop every borrow; the last owned immutable sample is safe to retain. */
10
+ dispose(): void;
11
+ }
12
+ //# sourceMappingURL=SequencePlayer.d.ts.map
@@ -0,0 +1,69 @@
1
+ import { Bitmap, applyBitmapAtlasFrame, readBitmapBinding, readBitmapImage } from './Bitmap.js';
2
+ import { EgretError } from './EgretError.js';
3
+ import { commitBinding, engineOf } from './ownership.js';
4
+ import { sampleSequenceClip } from './sequenceClip.js';
5
+ const states = new WeakMap();
6
+ // Capture the trusted operation once; caller overrides never supply crop authority.
7
+ const setCrop = Object.getOwnPropertyDescriptor(Bitmap.prototype, 'sourceRect').set;
8
+ function stateOf(receiver) {
9
+ const state = states.get(receiver);
10
+ if (state === undefined)
11
+ throw new EgretError('SEQ_PLAYER_INVALID');
12
+ return state;
13
+ }
14
+ /** Explicit absolute-time selection borrowing a target and its exact current lease. */
15
+ export class SequencePlayer {
16
+ constructor(bitmap, clip, mode = 'once') {
17
+ const target = readBitmapBinding(bitmap);
18
+ if (target === undefined)
19
+ throw new EgretError('BITMAP_TEXTURE_REQUIRED');
20
+ const snapshot = readBitmapImage(target.lease);
21
+ if (mode !== 'once' && mode !== 'loop')
22
+ throw new EgretError('SEQ_INPUT_INVALID');
23
+ // Authenticate before reading even frozen-looking public clip dimensions.
24
+ sampleSequenceClip(clip, 0, { mode });
25
+ const { image, sourceRect } = snapshot;
26
+ if (snapshot.viewRegion !== null ||
27
+ sourceRect.x !== 0 ||
28
+ sourceRect.y !== 0 ||
29
+ sourceRect.width !== image.width ||
30
+ sourceRect.height !== image.height ||
31
+ clip.atlasWidth !== image.width ||
32
+ clip.atlasHeight !== image.height) {
33
+ throw new EgretError('SEQ_ATLAS_MISMATCH');
34
+ }
35
+ states.set(this, { binding: { bitmap, lease: target.lease, clip, mode }, lastSample: undefined });
36
+ // Affinity survives disposal, but cleanup belongs only to an adopting Scope.
37
+ commitBinding([this], engineOf(bitmap));
38
+ }
39
+ applyAt(elapsedSeconds) {
40
+ const state = stateOf(this);
41
+ const binding = state.binding;
42
+ if (binding === undefined)
43
+ throw new EgretError('SEQ_PLAYER_DISPOSED');
44
+ const target = readBitmapBinding(binding.bitmap);
45
+ // Exact identity precedes entitlement, including a cleared target slot.
46
+ if (target?.lease !== binding.lease)
47
+ throw new EgretError('SEQ_BINDING_CHANGED');
48
+ readBitmapImage(binding.lease);
49
+ const sample = sampleSequenceClip(binding.clip, elapsedSeconds, { mode: binding.mode });
50
+ if (sample.region.layout === undefined)
51
+ Reflect.apply(setCrop, binding.bitmap, [sample.region]);
52
+ else
53
+ applyBitmapAtlasFrame(binding.bitmap, sample.region);
54
+ // Crop and natural geometry have committed; only now publish the sample.
55
+ state.lastSample = sample;
56
+ return sample;
57
+ }
58
+ get lastSample() {
59
+ return stateOf(this).lastSample;
60
+ }
61
+ get isDisposed() {
62
+ return stateOf(this).binding === undefined;
63
+ }
64
+ /** Drop every borrow; the last owned immutable sample is safe to retain. */
65
+ dispose() {
66
+ stateOf(this).binding = undefined;
67
+ }
68
+ }
69
+ //# sourceMappingURL=SequencePlayer.js.map
@@ -0,0 +1,8 @@
1
+ import { DisplayObjectContainer } from './DisplayObjectContainer.js';
2
+ import { Graphics } from './Graphics.js';
3
+ /** Stable drawing facade; a Sprite never shares or rebinds its Graphics. */
4
+ export declare class Sprite extends DisplayObjectContainer {
5
+ readonly graphics: Graphics;
6
+ constructor();
7
+ }
8
+ //# sourceMappingURL=Sprite.d.ts.map
package/dist/Sprite.js ADDED
@@ -0,0 +1,12 @@
1
+ import { DisplayObjectContainer } from './DisplayObjectContainer.js';
2
+ import { Graphics } from './Graphics.js';
3
+ /** Stable drawing facade; a Sprite never shares or rebinds its Graphics. */
4
+ export class Sprite extends DisplayObjectContainer {
5
+ graphics;
6
+ constructor() {
7
+ super();
8
+ this.graphics = new Graphics(this);
9
+ Object.defineProperty(this, 'graphics', { value: this.graphics, writable: false, configurable: false });
10
+ }
11
+ }
12
+ //# sourceMappingURL=Sprite.js.map
@@ -0,0 +1,14 @@
1
+ import { DisplayObjectContainer } from "./DisplayObjectContainer.js";
2
+ import type { DisplayObject } from "./DisplayObject.js";
3
+ import type { HitTestOptions } from "./displayHitTest.js";
4
+ import { ASSERT_ATTACHABLE } from "./ownership.js";
5
+ import type { EngineContext } from "./ownership.js";
6
+ export declare let createStage: (engine: EngineContext) => Stage;
7
+ /** Created and bound by Engine; there is no implicit global stage. */
8
+ export declare class Stage extends DisplayObjectContainer {
9
+ private constructor();
10
+ /** Pick one authored input area after complete structural/arithmetic admission. */
11
+ hitTest(globalX: number, globalY: number, options?: HitTestOptions): DisplayObject | undefined;
12
+ [ASSERT_ATTACHABLE](): void;
13
+ }
14
+ //# sourceMappingURL=Stage.d.ts.map
package/dist/Stage.js ADDED
@@ -0,0 +1,31 @@
1
+ import { DisplayObjectContainer } from "./DisplayObjectContainer.js";
2
+ import { queryDisplayHit } from "./displayHitTest.js";
3
+ import { ASSERT_ATTACHABLE, bind } from "./ownership.js";
4
+ import { EgretError } from "./EgretError.js";
5
+ import { markStageRoot } from "./displayTreeState.js";
6
+ import { createPreparedDisplayOperations } from "./preparedDisplaySubtree.js";
7
+ export let createStage;
8
+ const CREATION_TOKEN = Symbol("egret.stageFactory");
9
+ /** Created and bound by Engine; there is no implicit global stage. */
10
+ export class Stage extends DisplayObjectContainer {
11
+ constructor(engine, token) {
12
+ super();
13
+ if (token !== CREATION_TOKEN)
14
+ throw new EgretError("STAGE_FACTORY_REQUIRED");
15
+ markStageRoot(this);
16
+ bind(this, engine);
17
+ engine.registerPreparedDisplayOperations?.(createPreparedDisplayOperations(this));
18
+ }
19
+ static {
20
+ createStage = (engine) => new Stage(engine, CREATION_TOKEN);
21
+ }
22
+ /** Pick one authored input area after complete structural/arithmetic admission. */
23
+ hitTest(globalX, globalY, options) {
24
+ return queryDisplayHit(this, globalX, globalY, options);
25
+ }
26
+ // A Stage is an engine root and cannot become another display node's child.
27
+ [ASSERT_ATTACHABLE]() {
28
+ throw new EgretError("STAGE_ROOT_ONLY");
29
+ }
30
+ }
31
+ //# sourceMappingURL=Stage.js.map
@@ -0,0 +1,30 @@
1
+ import type { ImageData2D, TextureRegion2D, TextureViewRegionInput2D, TextureViewRegion2D } from "@egret/contracts";
2
+ /** An immutable CPU image view with a separate, terminal wrapper lifetime. */
3
+ export declare class Texture {
4
+ private readonly textureBrand;
5
+ private constructor();
6
+ get imageData(): ImageData2D;
7
+ get sourceRect(): TextureRegion2D;
8
+ get viewRegion(): TextureViewRegion2D | null;
9
+ get width(): number;
10
+ get height(): number;
11
+ get isDisposed(): boolean;
12
+ /** Drop only the wrapper reference; saved image values keep their own pixels. */
13
+ dispose(): void;
14
+ }
15
+ /** A texture of a whole image or of a rectangle of it. */
16
+ export declare function createTexture(image: ImageData2D, sourceRect?: TextureRegion2D): Texture;
17
+ /** Create an explicit logical view over an authentic straight CPU image. */
18
+ export declare function createTextureView(image: ImageData2D, region: TextureViewRegionInput2D): Texture;
19
+ /** Brand-only: disposal does not change the identity of a Texture. */
20
+ export declare function isTexture(value: unknown): value is Texture;
21
+ export interface TextureSnapshot2D {
22
+ readonly image: ImageData2D;
23
+ readonly sourceRect: TextureRegion2D;
24
+ readonly viewRegion: TextureViewRegion2D | null;
25
+ }
26
+ /** The image alone, under the checks of `readTextureSnapshot` and without a record of its own. */
27
+ export declare function readTextureImage(texture: Texture): ImageData2D;
28
+ /** Runtime-private authority; never consult subclass-overridable getters. */
29
+ export declare function readTextureSnapshot(texture: Texture): TextureSnapshot2D;
30
+ //# sourceMappingURL=Texture.d.ts.map
@@ -0,0 +1,178 @@
1
+ import { isImageData2D } from "@egret/contracts";
2
+ import { EgretError } from "./EgretError.js";
3
+ // Capture the original intrinsic before descriptor callbacks can replace it;
4
+ // Texture snapshots must not introduce late callbacks inside resource checkpoints.
5
+ const freeze = Object.freeze;
6
+ const apply = Reflect.apply;
7
+ const isArray = Array.isArray;
8
+ const safeInteger = Number.isSafeInteger;
9
+ const TypeFault = TypeError;
10
+ const RangeFault = RangeError;
11
+ const weakGet = WeakMap.prototype.get;
12
+ const weakSet = WeakMap.prototype.set;
13
+ const weakHas = WeakMap.prototype.has;
14
+ const CREATION_TOKEN = Symbol("egret.textureFactory");
15
+ const states = new WeakMap();
16
+ let createInstance;
17
+ function stateOf(value) {
18
+ const state = apply(weakGet, states, [value]);
19
+ if (state === undefined)
20
+ throw new EgretError("TEXTURE_INVALID");
21
+ return state;
22
+ }
23
+ /** Snapshot every known field before validation; no callbacks occur at commit. */
24
+ function copyRegion(image, input) {
25
+ if (input === undefined)
26
+ return freeze({ x: 0, y: 0, width: image.width, height: image.height });
27
+ try {
28
+ if (input === null || typeof input !== "object")
29
+ throw new TypeError("Texture region must be a record");
30
+ const x = input.x, y = input.y, width = input.width, height = input.height;
31
+ for (const [value, positive] of [
32
+ [x, false],
33
+ [y, false],
34
+ [width, true],
35
+ [height, true]
36
+ ]) {
37
+ if (typeof value !== "number")
38
+ throw new TypeError("Texture region fields must be numbers");
39
+ if (!Number.isSafeInteger(value) || (positive ? value <= 0 : value < 0))
40
+ throw new RangeError("Texture region integer range");
41
+ }
42
+ const right = x + width, bottom = y + height;
43
+ if (!Number.isSafeInteger(right) || !Number.isSafeInteger(bottom) || right > image.width || bottom > image.height) {
44
+ throw new RangeError("Texture region exceeds its image");
45
+ }
46
+ return freeze({ x: x === 0 ? 0 : x, y: y === 0 ? 0 : y, width, height });
47
+ }
48
+ catch (cause) {
49
+ throw new EgretError("TEXTURE_REGION_INVALID", { cause });
50
+ }
51
+ }
52
+ function viewInteger(value, positive, maximum) {
53
+ if (typeof value !== "number")
54
+ throw new TypeFault("Texture view region fields must be numbers");
55
+ if (!safeInteger(value) || (positive ? value <= 0 : value < 0) || value > maximum) {
56
+ throw new RangeFault("Texture view region integer range");
57
+ }
58
+ return value === 0 ? 0 : value;
59
+ }
60
+ /** Stage the entire region before validation, then own both immutable records. */
61
+ function copyViewRegion(image, input) {
62
+ try {
63
+ if (typeof input !== "object" || input === null || isArray(input)) {
64
+ throw new TypeFault("Texture view region must be a record");
65
+ }
66
+ const packedInput = input.packed;
67
+ const logicalWidthInput = input.logicalWidth;
68
+ const logicalHeightInput = input.logicalHeight;
69
+ const trimXInput = input.trimX;
70
+ const trimYInput = input.trimY;
71
+ const quarterTurnInput = input.quarterTurn;
72
+ // A late top-level getter outranks an earlier malformed packed record.
73
+ if (typeof packedInput !== "object" || packedInput === null || isArray(packedInput)) {
74
+ throw new TypeFault("Texture view region must be a record");
75
+ }
76
+ const xInput = packedInput.x;
77
+ const yInput = packedInput.y;
78
+ const widthInput = packedInput.width;
79
+ const heightInput = packedInput.height;
80
+ const x = viewInteger(xInput, false, 1048576);
81
+ const y = viewInteger(yInput, false, 1048576);
82
+ const width = viewInteger(widthInput, true, 1048576);
83
+ const height = viewInteger(heightInput, true, 1048576);
84
+ const logicalWidth = viewInteger(logicalWidthInput, true, 1048576);
85
+ const logicalHeight = viewInteger(logicalHeightInput, true, 1048576);
86
+ const trimX = viewInteger(trimXInput, false, 1048576);
87
+ const trimY = viewInteger(trimYInput, false, 1048576);
88
+ const quarterTurn = viewInteger(quarterTurnInput, false, 3);
89
+ const right = x + width, bottom = y + height;
90
+ if (!safeInteger(right) || !safeInteger(bottom) || right > image.width || bottom > image.height) {
91
+ throw new RangeFault("Texture view region exceeds its image");
92
+ }
93
+ const rotated = quarterTurn === 1 || quarterTurn === 3;
94
+ const contentWidth = rotated ? height : width;
95
+ const contentHeight = rotated ? width : height;
96
+ if (trimX + contentWidth > logicalWidth || trimY + contentHeight > logicalHeight) {
97
+ throw new RangeFault("Texture view content exceeds its logical region");
98
+ }
99
+ const packed = freeze({ x, y, width, height });
100
+ return freeze({ packed, logicalWidth, logicalHeight, trimX, trimY, quarterTurn: quarterTurn });
101
+ }
102
+ catch (cause) {
103
+ throw new EgretError("TEXTURE_VIEW_REGION_INVALID", { cause });
104
+ }
105
+ }
106
+ /** An immutable CPU image view with a separate, terminal wrapper lifetime. */
107
+ export class Texture {
108
+ constructor(image, sourceRect, token, viewRegion) {
109
+ if (token !== CREATION_TOKEN)
110
+ throw new EgretError("TEXTURE_FACTORY_REQUIRED");
111
+ // The original registry operation prevents descriptor callbacks from adding
112
+ // a new callback between completed CPU ownership and identity publication.
113
+ apply(weakSet, states, [this, freeze({ image, sourceRect, viewRegion })]);
114
+ }
115
+ static {
116
+ createInstance = (image, sourceRect, viewRegion = null) => new Texture(image, sourceRect, CREATION_TOKEN, viewRegion);
117
+ }
118
+ get imageData() {
119
+ return readTextureSnapshot(this).image;
120
+ }
121
+ get sourceRect() {
122
+ return stateOf(this).sourceRect;
123
+ }
124
+ get viewRegion() {
125
+ return stateOf(this).viewRegion;
126
+ }
127
+ get width() {
128
+ return stateOf(this).sourceRect.width;
129
+ }
130
+ get height() {
131
+ return stateOf(this).sourceRect.height;
132
+ }
133
+ get isDisposed() {
134
+ return stateOf(this).image === undefined;
135
+ }
136
+ /** Drop only the wrapper reference; saved image values keep their own pixels. */
137
+ dispose() {
138
+ const state = stateOf(this);
139
+ if (state.image !== undefined)
140
+ apply(weakSet, states, [
141
+ this,
142
+ freeze({ image: undefined, sourceRect: state.sourceRect, viewRegion: state.viewRegion })
143
+ ]);
144
+ }
145
+ }
146
+ /** A texture of a whole image or of a rectangle of it. */
147
+ export function createTexture(image, sourceRect) {
148
+ if (!isImageData2D(image))
149
+ throw new EgretError("TEXTURE_IMAGE_INVALID", { cause: new TypeError("Authentic ImageData2D required") });
150
+ return createInstance(image, copyRegion(image, sourceRect));
151
+ }
152
+ /** Create an explicit logical view over an authentic straight CPU image. */
153
+ export function createTextureView(image, region) {
154
+ if (!isImageData2D(image))
155
+ throw new EgretError("TEXTURE_IMAGE_INVALID", { cause: new TypeFault("Authentic ImageData2D required") });
156
+ const viewRegion = copyViewRegion(image, region);
157
+ // Instance allocation/registry failures are outside region-error wrapping.
158
+ return createInstance(image, viewRegion.packed, viewRegion);
159
+ }
160
+ /** Brand-only: disposal does not change the identity of a Texture. */
161
+ export function isTexture(value) {
162
+ return apply(weakHas, states, [value]);
163
+ }
164
+ /** The image alone, under the checks of `readTextureSnapshot` and without a record of its own. */
165
+ export function readTextureImage(texture) {
166
+ const image = stateOf(texture).image;
167
+ if (image === undefined)
168
+ throw new EgretError("TEXTURE_DISPOSED");
169
+ return image;
170
+ }
171
+ /** Runtime-private authority; never consult subclass-overridable getters. */
172
+ export function readTextureSnapshot(texture) {
173
+ const state = stateOf(texture);
174
+ if (state.image === undefined)
175
+ throw new EgretError("TEXTURE_DISPOSED");
176
+ return freeze({ image: state.image, sourceRect: state.sourceRect, viewRegion: state.viewRegion });
177
+ }
178
+ //# sourceMappingURL=Texture.js.map
@@ -0,0 +1,36 @@
1
+ import type { AssetAcquireOptions, AssetProvider } from "./AssetManager.js";
2
+ import type { AssetLease } from "./AssetLease.js";
3
+ import type { AssetRef, AssetType } from "./AssetRef.js";
4
+ import type { EngineContext } from "./ownership.js";
5
+ /** @internal Narrow immutable group assembly; no manager or owner lookup escapes. */
6
+ export interface AssetGroupOperations {
7
+ readonly admitGroupRefs: (refs: readonly unknown[]) => void;
8
+ readonly acquire: <T>(ref: AssetRef<T>, options?: AssetAcquireOptions) => Promise<AssetLease<T>>;
9
+ readonly claimGroupLease: (lease: unknown, group: object) => void;
10
+ readonly releaseGroupLease: (lease: unknown) => void;
11
+ }
12
+ /** Private authority installed only by authentic AssetManager construction. */
13
+ interface AssetManagerOwner {
14
+ readonly context: EngineContext;
15
+ readonly assertOpen: () => void;
16
+ readonly register: <T>(type: AssetType<T>, provider: AssetProvider<NoInfer<T>>) => void;
17
+ readonly acquire: <T>(ref: AssetRef<T>, options?: AssetAcquireOptions) => Promise<AssetLease<T>>;
18
+ readonly invalidate: <T>(ref: AssetRef<T>) => void;
19
+ }
20
+ /** Called once from the manager constructor; no cache or provider import is needed. */
21
+ export declare function registerAssetManagerOwner(manager: object, owner: AssetManagerOwner): void;
22
+ /** Return the immutable intrinsic operations, never a structural caller port. */
23
+ export declare function requireAssetManagerOwner(value: unknown): AssetManagerOwner;
24
+ /** Only pre-commit preparation can be retried; the release callback is idempotent. */
25
+ export declare function beginTextCacheCreation(manager: object): () => void;
26
+ /** Consume the sole lifetime before provider registration or the fixed 32 ref IDs. */
27
+ export declare function commitTextCacheLifetime(manager: object, closeCache: () => void): void;
28
+ /** Make the manager unavailable without invoking any cache or external callback. */
29
+ export declare function markAssetManagerOwnerClosed(manager: object): void;
30
+ /** Consume first; trusted cache close handles and diagnoses its own cleanup faults. */
31
+ export declare function closeOwnedTextCache(manager: object): void;
32
+ /** One additional fixed paragraph profile shares the same manager and shutdown boundary. */
33
+ export declare function beginParagraphCacheCreation(manager: object): () => void;
34
+ export declare function commitParagraphCacheLifetime(manager: object, close: () => void): void;
35
+ export {};
36
+ //# sourceMappingURL=assetManagerOwnerState.d.ts.map
@@ -0,0 +1,115 @@
1
+ import { EgretError } from "./EgretError.js";
2
+ const APPLY = Reflect.apply;
3
+ const WEAK_GET = WeakMap.prototype.get;
4
+ const WEAK_HAS = WeakMap.prototype.has;
5
+ const WEAK_SET = WeakMap.prototype.set;
6
+ const FREEZE = Object.freeze;
7
+ const states = new WeakMap();
8
+ function requireState(value) {
9
+ // Intrinsic lookup authenticates identity without any caller property read.
10
+ const state = APPLY(WEAK_GET, states, [value]);
11
+ if (state === undefined)
12
+ throw new EgretError("TEXT_ASSETS_INVALID");
13
+ return state;
14
+ }
15
+ function assertOwnerOpen(state) {
16
+ // Preserve the original manager/Engine cause before any lifetime or busy refusal.
17
+ state.owner.assertOpen();
18
+ if (state.closed)
19
+ throw new EgretError("TEXT_CACHE_CLOSED");
20
+ }
21
+ /** Called once from the manager constructor; no cache or provider import is needed. */
22
+ export function registerAssetManagerOwner(manager, owner) {
23
+ if (APPLY(WEAK_HAS, states, [manager]))
24
+ throw new EgretError("TEXT_ASSETS_INVALID");
25
+ APPLY(WEAK_SET, states, [
26
+ manager,
27
+ {
28
+ owner: FREEZE(owner),
29
+ closed: false,
30
+ creationBusy: false,
31
+ lifetimeCommitted: false,
32
+ closeCache: undefined,
33
+ paragraphLifetimeCommitted: false,
34
+ closeParagraphCache: undefined
35
+ }
36
+ ]);
37
+ }
38
+ /** Return the immutable intrinsic operations, never a structural caller port. */
39
+ export function requireAssetManagerOwner(value) {
40
+ return requireState(value).owner;
41
+ }
42
+ /** Only pre-commit preparation can be retried; the release callback is idempotent. */
43
+ export function beginTextCacheCreation(manager) {
44
+ const state = requireState(manager);
45
+ assertOwnerOpen(state);
46
+ if (state.lifetimeCommitted)
47
+ throw new EgretError("TEXT_CACHE_ALREADY_CREATED");
48
+ if (state.creationBusy)
49
+ throw new EgretError("TEXT_CACHE_REENTRANT");
50
+ state.creationBusy = true;
51
+ let active = true;
52
+ return () => {
53
+ if (!active)
54
+ return;
55
+ active = false;
56
+ state.creationBusy = false;
57
+ };
58
+ }
59
+ /** Consume the sole lifetime before provider registration or the fixed 32 ref IDs. */
60
+ export function commitTextCacheLifetime(manager, closeCache) {
61
+ const state = requireState(manager);
62
+ assertOwnerOpen(state);
63
+ if (state.lifetimeCommitted)
64
+ throw new EgretError("TEXT_CACHE_ALREADY_CREATED");
65
+ if (!state.creationBusy)
66
+ throw new EgretError("TEXT_CACHE_REENTRANT");
67
+ state.lifetimeCommitted = true;
68
+ state.closeCache = closeCache;
69
+ }
70
+ /** Make the manager unavailable without invoking any cache or external callback. */
71
+ export function markAssetManagerOwnerClosed(manager) {
72
+ requireState(manager).closed = true;
73
+ }
74
+ /** Consume first; trusted cache close handles and diagnoses its own cleanup faults. */
75
+ export function closeOwnedTextCache(manager) {
76
+ const state = requireState(manager);
77
+ const closeCache = state.closeCache;
78
+ state.closeCache = undefined;
79
+ const closeParagraphCache = state.closeParagraphCache;
80
+ state.closeParagraphCache = undefined;
81
+ try {
82
+ closeCache?.();
83
+ }
84
+ finally {
85
+ closeParagraphCache?.();
86
+ }
87
+ }
88
+ /** One additional fixed paragraph profile shares the same manager and shutdown boundary. */
89
+ export function beginParagraphCacheCreation(manager) {
90
+ const state = requireState(manager);
91
+ assertOwnerOpen(state);
92
+ if (state.paragraphLifetimeCommitted)
93
+ throw new EgretError("PARAGRAPH_CACHE_ALREADY_CREATED");
94
+ if (state.creationBusy)
95
+ throw new EgretError("TEXT_CACHE_REENTRANT");
96
+ state.creationBusy = true;
97
+ let active = true;
98
+ return () => {
99
+ if (active) {
100
+ active = false;
101
+ state.creationBusy = false;
102
+ }
103
+ };
104
+ }
105
+ export function commitParagraphCacheLifetime(manager, close) {
106
+ const state = requireState(manager);
107
+ assertOwnerOpen(state);
108
+ if (state.paragraphLifetimeCommitted)
109
+ throw new EgretError("PARAGRAPH_CACHE_ALREADY_CREATED");
110
+ if (!state.creationBusy)
111
+ throw new EgretError("TEXT_CACHE_REENTRANT");
112
+ state.paragraphLifetimeCommitted = true;
113
+ state.closeParagraphCache = close;
114
+ }
115
+ //# sourceMappingURL=assetManagerOwnerState.js.map