@shopware-ag/dive 3.0.11 → 4.0.0

package/build/engine/Dive.d.ts

@@ -1,9 +1,8 @@
 import { DIVEClock } from './clock/Clock.ts';
 import { DIVEView } from './view/View.ts';
 import { DIVEScene, DIVESceneSettings } from './scene/Scene.ts';
-import { DIVEPerspectiveCameraSettings } from './camera/PerspectiveCamera.ts';
+import { DIVEPerspectiveCameraSettings } from '../components/camera/perspective/PerspectiveCameraComponent.ts';
 import { DIVERendererSettings } from './renderer/Renderer.ts';
-import { OrbitControllerSettings } from '../plugins/orbitcontroller/index.ts';
 declare global {
     interface Window {
         DIVE: {
@@ -15,6 +14,12 @@ declare global {
              * Get the first instance of DIVE
              */
             get instance(): DIVE | undefined;
+            /**
+             * Maximum amount of DIVE instances that can be created. This is checked on initialization of a new instance.
+             *
+             * You can change this value to allow more instances, but be aware that this can lead to performance issues and crashes.
+             */
+            instanceLimit: number;
         };
     }
 }
@@ -31,13 +36,13 @@ export type DIVESettings = {
      * @default false
      */
     displayAxes: boolean;
-} & DIVESceneSettings & DIVEPerspectiveCameraSettings & DIVERendererSettings & OrbitControllerSettings;
+} & DIVESceneSettings & DIVEPerspectiveCameraSettings & DIVERendererSettings;
 export declare const DIVEDefaultSettings: Required<DIVESettings>;
 /**
  * #### DIVE
  * is the main class of the DIVE framework.
  *
- * An instance of this class delivers a complete 3D environment with a perspective camera, orbit controls, a toolbox, and a communication system.
+ * An instance of this class delivers a complete 3D environment with a perspective camera and orbit controls.
  * ```ts
  * import { DIVE } from "@shopware-ag/dive";
  *
@@ -45,13 +50,16 @@ export declare const DIVEDefaultSettings: Required<DIVESettings>;
  *
  * const dive = new DIVE();
  *
- * myWrapper.appendChild(dive.Canvas);
+ * myWrapper.appendChild(dive.canvas);
+ * ```
  *
- * dive.Communication.subscribe('GET_ALL_SCENE_DATA', () => {
- *  // do something
- * }));
+ * Driving a scene from data is the job of the state plugin, which wraps a
+ * DIVE instance rather than being part of it:
+ * ```ts
+ * import { State } from "@shopware-ag/dive/state";
  *
- * dive.Communication.performAction('GET_ALL_SCENE_DATA', {});
+ * const state = new State(dive, orbitController);
+ * await state.performAction('SET_STATE', sceneData);
  * ```
  * @module
  */
@@ -70,10 +78,6 @@ export declare class DIVE {
     get canvas(): HTMLCanvasElement;
     get scene(): DIVEScene;
     get clock(): DIVEClock;
-    /**
-     * @deprecated Use startAsync() instead, which returns a promise that resolves when the engine is fully initialized.
-     */
-    start(): void;
     startAsync(): Promise<void>;
     stop(): void;
     disposeAsync(): Promise<void>;

package/build/engine/boundingbox/BoundingBox.d.ts

@@ -0,0 +1,76 @@
+import { Box3, Matrix4, Sphere, Vector3, Object3D } from 'three/webgpu';
+/**
+ * The box that encloses a set of objects.
+ *
+ * A measurement and nothing else: no place in the scene graph, no owner, no
+ * visualisation. {@link BoundingBoxComponent} is what gives a node one of these
+ * and keeps it current; anything that just needs the numbers builds one here.
+ *
+ * Two shapes:
+ *
+ * - {@link enclose} is axis-aligned in world space. What camera framing wants,
+ *   and what `size` means for a whole scene.
+ * - {@link encloseOriented} is axis-aligned in a frame that carries another
+ *   object's position and rotation but not its scale. The box hugs a turned
+ *   object instead of enclosing its world projection, and `size` becomes the
+ *   object's own width, height and depth in world units. A 2 x 1 x 1 object
+ *   turned 45 degrees measures 2 x 1 x 1 oriented and 2.121 x 1 x 2.121
+ *   world-aligned.
+ *
+ * `center` and `sphere` are in world space either way, so code that frames a
+ * camera never has to ask which shape it was handed. Only `box` and `size` live
+ * in the measured frame, and {@link frame} is how they get to the world.
+ *
+ * Reused rather than rebuilt: enclosing again overwrites what is there, so a
+ * caller that measures repeatedly allocates once.
+ *
+ * Only geometry that {@link computeProductBounds} counts as real is measured, so
+ * helpers, the ground plane and gizmo handles never widen a box.
+ *
+ * @module
+ */
+export declare class BoundingBox {
+    readonly isBoundingBox: true;
+    private _box;
+    private _sphere;
+    private _center;
+    private _size;
+    private _frame;
+    private _oriented;
+    /** The box itself, in the frame it was measured in. */
+    get box(): Box3;
+    /** Width, height and depth, in the frame the box was measured in. */
+    get size(): Vector3;
+    /** The centre of the box, in world space. */
+    get center(): Vector3;
+    /** The sphere around the box, in world space. */
+    get sphere(): Sphere;
+    /** The radius of that sphere. */
+    get radius(): number;
+    /** How the measured frame relates to the world. Identity when world-aligned. */
+    get frame(): Matrix4;
+    /** Whether anything was found to measure. */
+    get isEmpty(): boolean;
+    /**
+     * Measures a world-aligned box around everything given.
+     *
+     * @param objects - What to enclose, with everything below it.
+     */
+    enclose(objects: Object3D | readonly Object3D[]): this;
+    /**
+     * Measures a box aligned to another object's axes.
+     *
+     * @param objects - What to enclose, with everything below it.
+     * @param frame - Whose axes to align to. Its position and rotation are taken,
+     * its scale is not: the scale belongs in the extents, or `size` would report
+     * the geometry's own numbers rather than the size in the scene.
+     */
+    encloseOriented(objects: Object3D | readonly Object3D[], frame: Object3D): this;
+    /** Empties the box, for when there is nothing to measure. */
+    clear(): this;
+    private _measure;
+    /** Turns the measured box into the world-space figures. */
+    private _derive;
+    /** The distance from the world centre to the furthest corner. */
+    private _worldRadius;
+}

package/build/engine/component/Component.d.ts

@@ -0,0 +1,236 @@
+import { EventDispatcher, Object3D } from 'three/webgpu';
+import { DIVENode } from '../node/Node.ts';
+import { DIVEComponentEventMap } from '../../types/events/DIVEComponentEventMap.ts';
+/**
+ * Base class for everything that gives a node a capability: geometry, a light,
+ * a label, a helper visualisation, per-frame behaviour.
+ *
+ * A component is **not** part of the scene graph. What it owns is: three rebuilds
+ * its render list by walking the graph every single frame, so a mesh or a light
+ * has to be in `children` to be drawn -- but it goes into the *node's* children,
+ * through {@link contribute}. The component itself stays out, because an exporter
+ * writes a node for everything it walks, so a component in the graph would cost
+ * one level per component per save.
+ *
+ * The two rules worth knowing before writing one:
+ *
+ * 1. **Contribute your content, do not parent it.** `contribute` puts objects
+ *    into the owner's children and takes them along when the component moves;
+ *    `withdraw` takes them back. Anything that needs an internal offset carries
+ *    it on the object contributed -- a directional light's direction lives on the
+ *    light. A component has no transform of its own to offer.
+ * 2. **Never attach another component.** Contribute all the objects you like --
+ *    `PointLightComponent` contributes a light and a clickable proxy sphere --
+ *    but never call `owner.addComponent`. A component describes one capability
+ *    and does not decide what else its owner is made of; composing a node is the
+ *    caller's job. A component that needs a sibling should be handed it, or the
+ *    caller should attach both.
+ *
+ * Constructors take no arguments: {@link clone} calls `new this.constructor()`.
+ * Configure through setters instead.
+ *
+ * An `EventDispatcher`, so a component reports what happens to it on itself. A
+ * detached one can speak too, which is why nothing here guards a report with
+ * {@link isAttached}: whether an event fires says something about the event, never
+ * about the delivery route.
+ *
+ * A component is not in the `.parent` chain, but what it contributes is, and
+ * `findInterface` walks that chain up from a raycast hit looking for
+ * `isSelectable` and friends. A capability brand on a contributed mesh therefore
+ * gets the mesh handed back instead of the node behind it. Contribute plain
+ * objects and let the node carry the brands.
+ *
+ * @module
+ */
+export declare abstract class DIVEComponent extends EventDispatcher<DIVEComponentEventMap> {
+    readonly isDIVEComponent: true;
+    /** For debugging: nothing reads it, since components are not in the graph. */
+    name: string;
+    /**
+     * The node this component is attached to.
+     *
+     * Throws while the component is detached, rather than handing out a `null`
+     * that every consumer has to rule out. A non-nullable owner is not available
+     * to us: {@link clone} builds a component before there is any node to put it
+     * on, so a detached one has to be constructible, and detached is therefore a
+     * real state rather than an impossible one.
+     *
+     * Ask {@link isAttached} when a detached component is a case to handle rather
+     * than a mistake.
+     */
+    get owner(): DIVENode;
+    /**
+     * What this component put into its owner's children.
+     *
+     * A component owns renderables -- a mesh, a light, a camera, a helper -- but
+     * they belong in the *node's* children, not in its own. `children` is three's
+     * render queue, so the content has to be in the graph; the component holding
+     * it does not, and an exporter writes every graph node it walks. One level
+     * per component per save is what that costs.
+     *
+     * Contribute through {@link contribute}, take back through {@link withdraw}.
+     * Both work whether or not the component is attached: while it has no owner
+     * this is a list and nothing more, and everything on it is added the moment
+     * one arrives.
+     */
+    get contributions(): readonly Object3D[];
+    private _contributed;
+    /**
+     * Whether this component is attached to a node.
+     */
+    get isAttached(): boolean;
+    private _owner;
+    /**
+     * Whether this component currently participates in the per-frame tick.
+     *
+     * Only meaningful for components that implement {@link tick}. Enrolment and
+     * participation are separate questions: whether a component can ever tick is
+     * decided by the method existing, while this decides whether it does right
+     * now, so one that only works some of the time can withdraw entirely instead
+     * of being called every frame to return immediately.
+     */
+    get tickEnabled(): boolean;
+    private _tickEnabled;
+    /**
+     * Implement to receive a per-frame callback.
+     *
+     * The mere presence of this method enrols the component; components without
+     * it are never visited. Needs the camera? Put an `onBeforeRender` on the
+     * meshes the component owns instead -- `tick` has no view context.
+     *
+     * @param deltaTime - Seconds since the previous frame.
+     */
+    tick?(deltaTime: number): void;
+    /**
+     * Enables or disables this component's per-frame tick.
+     *
+     * @param enabled - Whether the component should tick.
+     */
+    setTickEnabled(enabled: boolean): void;
+    /**
+     * Called once the component has been attached to a node.
+     *
+     * @param owner - The node it is now attached to.
+     */
+    protected onAttach(owner: DIVENode): void;
+    /**
+     * Called after the component has been detached from a node.
+     *
+     * Takes the previous owner explicitly because three clears `parent` before
+     * dispatching `removed`, so `this.owner` is already `null` by this point.
+     *
+     * @param previousOwner - The node it was attached to.
+     */
+    protected onDetach(previousOwner: DIVENode): void;
+    /**
+     * Puts objects into the owner's children, and remembers them.
+     *
+     * Safe to call from a constructor: with no owner yet this only records them,
+     * and {@link contributions} is applied as soon as one arrives. Safe to call
+     * twice with the same object -- the second time is ignored rather than
+     * producing a duplicate, which would send a spurious `childremoved` /
+     * `childadded` pair through the owner.
+     *
+     * @param objects - What this component contributes to its owner.
+     */
+    protected contribute(...objects: Object3D[]): void;
+    /**
+     * Takes objects back out of the owner's children.
+     *
+     * Only unparents them. Disposing is a separate concern: a component that is
+     * merely moving to another node must not destroy what it carries.
+     *
+     * @param objects - What to take back. Anything not contributed is ignored.
+     */
+    protected withdraw(...objects: Object3D[]): void;
+    /**
+     * Releases GPU resources held by this component.
+     *
+     * Subclasses owning geometries, materials or textures must override this.
+     */
+    dispose(): void;
+    /**
+     * Hands the contributions to a new owner.
+     *
+     * Adds only what is not already there, so a stray direct assignment to
+     * `node.children` cannot leave this out of step -- and so re-attaching a
+     * component that never left is a no-op.
+     */
+    private _adopt;
+    /**
+     * Called by {@link DIVENode.addComponent}. Not for anyone else.
+     *
+     * three's `added`/`removed` events used to drive this, which caught every way
+     * into the graph -- `add`, `attach`, `clear`, re-parenting. A component is no
+     * longer in the graph, so the node is now the only way in, and that is what
+     * makes this reliable rather than what makes it fragile.
+     *
+     * @internal
+     */
+    _attach(owner: DIVENode): void;
+    /**
+     * Called by {@link DIVENode.removeComponent}. Not for anyone else.
+     *
+     * @internal
+     */
+    _detach(): void;
+    /**
+     * A component of the same kind, configured the same way.
+     *
+     * Calls `new this.constructor()`, which is why constructors take no
+     * arguments, and hands over to {@link copy}.
+     */
+    clone(): this;
+    /**
+     * Takes on another component's configuration.
+     *
+     * The base copies the name and nothing else. A component holding state --
+     * a geometry descriptor, a material, an intensity factor -- overrides this
+     * and copies it, because a clone that silently drops it looks like it worked.
+     *
+     * Never copies contributions: the clone builds or loads its own.
+     *
+     * @param source - The component to copy from.
+     */
+    copy(source: this): this;
+}
+/**
+ * The component that contributed `object`, if any.
+ *
+ * @param object - Something found in a node's children.
+ */
+export declare function contributedBy(object: Object3D): DIVEComponent | undefined;
+/**
+ * Any component class, for `instanceof` lookups.
+ *
+ * Uses `never[]` parameters so abstract bases that take constructor arguments
+ * still match -- only the class identity matters here, never its signature.
+ * Concrete components must still be zero-argument so `clone()` works.
+ */
+export type DIVEComponentClass<T extends DIVEComponent = DIVEComponent> = abstract new (...args: never[]) => T;
+/**
+ * Type guard for components, without importing the class.
+ *
+ * @param object - The object to test.
+ */
+export declare function isDIVEComponent(object: unknown): object is DIVEComponent;
+/**
+ * Walks **up** from an object to the component that contains it.
+ *
+ * The counterpart to `DIVENode.getComponent`, which looks at a node's own
+ * components: this starts anywhere inside one and finds the component itself.
+ * That is how a caller holding only what a component owns gets back to it -- an
+ * `OrbitController` hands out its camera, and `setCameraLayer` lives on the
+ * camera's component.
+ *
+ * Walks up from `object`, asking at each step which component contributed it --
+ * a component owns its content but does not parent it, so it is not an ancestor.
+ * Going up as well as asking means this still finds a component from something
+ * nested deep inside what it contributed.
+ *
+ * Matches with `instanceof`, so an abstract base finds its subclasses.
+ *
+ * @param object - Where to start, typically something a component owns.
+ * @param Ctor - The component class to look for.
+ */
+export declare function findComponent<T extends DIVEComponent>(object: Object3D, Ctor: DIVEComponentClass<T>): T | undefined;

package/build/engine/environment/Environment.d.ts

@@ -18,30 +18,12 @@ export type DIVEEnvironmentSettings = {
      * @default false
      */
     useAsBackground: boolean;
-    /**
-     * The intensity of the environment lighting.
-     *
-     * @default 1
-     */
-    globalEnvIntensity: number;
-    /**
-     * The exposure of the HDR image.
-     *
-     * @default 1
-     */
-    exposure: number;
     /**
      * The rotation of the HDR image in radians.
      *
      * @default 0
      */
     rotateY: number;
-    /**
-     * Whether to replace the existing lights (can be restored via `restoreLights`).
-     *
-     * @default false
-     */
-    replaceLights?: boolean;
 };
 export declare const DIVEEnvironmentDefaultSettings: DIVEEnvironmentSettings;
 /**
@@ -53,6 +35,7 @@ export declare const DIVEEnvironmentDefaultSettings: DIVEEnvironmentSettings;
  */
 export declare class DIVEEnvironment {
     private originalBackground;
+    private installedBackground;
     private _webgpurenderer;
     private scene;
     private pmrem;
@@ -71,6 +54,13 @@ export declare class DIVEEnvironment {
      * Disposes the environment.
      */
     dispose(): void;
+    /**
+     * Whether `scene.background` is still the one this environment installed.
+     *
+     * A foreign value means something else has changed the background in the
+     * meantime, which makes it the value to restore instead.
+     */
+    private ownsSceneBackground;
     private clearEnvironment;
     /**
      * Updates the environment.

package/build/engine/index.d.ts

@@ -1,5 +1,7 @@
 export * from './Dive.ts';
-export * from './camera/PerspectiveCamera.ts';
+export * from './component/Component.ts';
+export * from './node/Node.ts';
+export * from './boundingbox/BoundingBox.ts';
 export * from './clock/Clock.ts';
 export * from './renderer/Renderer.ts';
 export * from './environment/Environment.ts';
@@ -7,4 +9,5 @@ export * from './canvas/CanvasLifecycleManager.ts';
 export * from './promise/deferred/DeferredPromise.ts';
 export * from './promise/abortable/AbortablePromise.ts';
 export * from './scene/Scene.ts';
+export * from './scene/root/Root.ts';
 export * from './view/View.ts';

package/build/engine/node/Node.d.ts

@@ -0,0 +1,189 @@
+import { Box3, Object3D, Vector3, Vector3Like } from 'three/webgpu';
+import { DIVEMovable } from '../../interfaces/Movable.ts';
+import { DIVESelectable } from '../../interfaces/Selectable.ts';
+import { TransformControls } from 'three/examples/jsm/controls/TransformControls.ts';
+import { DIVEEntityEventMap } from '../../types/events/index.ts';
+import { DIVEComponent, DIVEComponentClass } from '../component/Component.ts';
+/**
+ * A node in the scene tree.
+ *
+ * Nodes carry the transform and the identity; everything they *do* comes from
+ * the components attached to them. `children` holds both -- it has to, because
+ * three builds its render list from the scene graph -- so use `nodes` for the
+ * logical child tree and `components` for the attached capabilities.
+ *
+ * @module
+ */
+export declare class DIVENode extends Object3D<DIVEEntityEventMap> implements DIVESelectable, DIVEMovable {
+    readonly isSelectable: true;
+    readonly isMovable: true;
+    readonly isDIVENode: true;
+    gizmo: TransformControls | null;
+    protected _positionWorldBuffer: Vector3;
+    protected _boundingBox: Box3;
+    private _components;
+    /** The scene this node belongs to, cached so it survives detachment. */
+    private _scene;
+    /**
+     * The components attached to this node.
+     */
+    get components(): readonly DIVEComponent[];
+    /**
+     * The child nodes of this node -- the logical scene tree.
+     *
+     * Filters `children` by `isDIVENode`, which excludes components as well as
+     * raw geometry a component happens to own. Uncached on purpose: direct
+     * `children` assignment bypasses three's events, so a cache would be able
+     * to go stale, and the list is short enough that filtering costs nothing.
+     */
+    get nodes(): DIVENode[];
+    constructor();
+    /**
+     * Attaches a component to this node.
+     *
+     * Uses `add`, never `attach`: a component has no meaningful transform of its
+     * own, and `attach` would apply an inverse world matrix to it.
+     *
+     * Announces itself with `componentadded`, named after three's `childadded`
+     * because it is the same kind of fact about the same node. A component is not
+     * a child, so three's own events say nothing about one, and without this
+     * nothing could observe what a node is made of.
+     *
+     * @param component - The component to attach.
+     * @returns The component, for chaining.
+     */
+    addComponent<T extends DIVEComponent>(component: T): T;
+    /**
+     * Detaches a component from this node.
+     *
+     * Announces itself with `componentremoved`, after the component is gone, so a
+     * listener that re-reads the node sees what is left rather than what was.
+     *
+     * @param component - The component to detach.
+     */
+    removeComponent(component: DIVEComponent): this;
+    /**
+     * Finds the first attached component of the given type.
+     *
+     * Matches with `instanceof`, so a base class finds its subclasses -- asking
+     * for `MeshComponent` also returns a `PrimitiveComponent`, and asking
+     * for an abstract base such as `DIVELightComponent` works too.
+     *
+     * @param Ctor - The component class to look for.
+     */
+    getComponent<T extends DIVEComponent>(Ctor: DIVEComponentClass<T>): T | undefined;
+    /**
+     * Finds every attached component of the given type.
+     *
+     * @param Ctor - The component class to look for.
+     */
+    getComponents<T extends DIVEComponent>(Ctor: DIVEComponentClass<T>): T[];
+    /**
+     * Like {@link getComponent}, but throws when the component is missing.
+     *
+     * Use this wherever a component is part of the node's contract -- a model
+     * node always has mesh geometry, a light node always has a light. Throwing
+     * once beats threading an `undefined` through every caller.
+     *
+     * @param Ctor - The component class to look for.
+     */
+    requireComponent<T extends DIVEComponent>(Ctor: DIVEComponentClass<T>): T;
+    /**
+     * Removes all child nodes and raw children, keeping what components own.
+     *
+     * `Object3D.clear()` would take the contributions with it, which would
+     * silently strip a node of its geometry or its light. A component gives up
+     * its own content through `withdraw`, never through the node.
+     */
+    clear(): this;
+    /**
+     * Copies another node, its components included.
+     *
+     * Child nodes are cloned, contributed content is not: a component brings its
+     * own along, and cloning it here as well would leave the copy with ownerless
+     * geometry beside a component that knows nothing about it.
+     *
+     * **Replaces the components this node already has, disposing them.** A node
+     * that attaches components in its constructor -- `DIVERoot` and its floor --
+     * would otherwise end up with two of each, and the ones being replaced hold
+     * GPU resources that nobody else will ever release. Unexpected for a copy
+     * operation, hence spelled out here.
+     *
+     * @param source - The node to copy from.
+     * @param recursive - Whether to copy children.
+     */
+    copy(source: this, recursive?: boolean): this;
+    /**
+     * Re-evaluates whether a component should be ticking.
+     *
+     * @param component - The component whose tick state changed.
+     * @internal
+     */
+    refreshComponentTick(component: DIVEComponent): void;
+    setPosition(position: Vector3Like): void;
+    setRotation(rotation: Vector3Like): void;
+    setScale(scale: Vector3Like): void;
+    /**
+     * Writes a transform **without reporting it for this node**.
+     *
+     * For a caller that announces the change itself: the state's apply path
+     * writes a whole patch and its action announces it once. Going through
+     * `setPosition`, `setRotation` and `setScale` there meant three reports for
+     * one patch, on top of the action's own — which is what this exists to avoid.
+     *
+     * Members are still woken, because nothing else tells them: their own
+     * transform did not change, but their world transform did, and no caller
+     * knows about them.
+     *
+     * @param patch - The parts of the transform to write. Anything absent is left
+     * alone.
+     */
+    applyTransform(patch: {
+        position?: Vector3Like | null;
+        rotation?: Vector3Like | null;
+        scale?: Vector3Like | null;
+    }): void;
+    /**
+     * Reports this node's transform, and its members' new world transforms.
+     *
+     * One event for every kind of move, so a listener never has to ask what
+     * caused it: a gizmo drag and a `setPosition` both arrive as
+     * `object-transform`.
+     *
+     * Can be called when the object is moved from a foreign object (gizmo,
+     * parent, etc.) to update the object's position.
+     */
+    onMove(): void;
+    /**
+     * Writes whatever the patch carries, guarded field by field.
+     *
+     * @returns Whether anything actually changed. Nothing reports otherwise, so
+     * a patch that repeats the current transform stays silent.
+     */
+    private _writeTransform;
+    /**
+     * Has every member report its new world transform, recursively.
+     *
+     * Members are reached through their own `onMove`, so a nested group carries
+     * on down its own members.
+     */
+    private _reportMembers;
+    /**
+     * Rests this node on the highest surface below it, and never below the
+     * ground plane.
+     *
+     * The floor is deliberately not a raycast target: it is a flat plane at
+     * y = 0, so "hit the floor" and "hit nothing" produce the same answer. The
+     * clamp to y = 0 covers the remaining case, geometry parked below the floor,
+     * which must not drag this node underground.
+     */
+    dropIt(): void;
+    setVisibility(visible: boolean): void;
+    setToWorldOrigin(): void;
+    onSelect(): void;
+    onDeselect(): void;
+    private _handleAddedToTree;
+    private _handleRemovedFromTree;
+    private _attachToScene;
+    private _detachFromScene;
+}

package/build/engine/promise/abortable/AbortablePromise.d.ts

@@ -13,5 +13,13 @@ export declare class DIVEAbortablePromise<T> implements Promise<T> {
     catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): Promise<T | TResult>;
     finally(onfinally?: (() => void) | null): Promise<T>;
     abort(reason?: unknown): void;
+    /**
+     * Runs the executor and hands back its promise.
+     *
+     * The `catch` is not redundant, unlike one inside an `async` function: this
+     * method is synchronous, so an executor that throws before its first `await`
+     * would throw at whoever called this rather than reject the promise they
+     * were handed.
+     */
     private _execute;
 }