narraleaf-react 0.47.2 → 1.0.1

package/dist/game/nlcore/elements/transform/type.d.ts

@@ -10,7 +10,7 @@ export declare namespace TransformDefinitions {
         delay: number;
         at: TransformDefinitions.SequenceAtDefinition;
     } & {
-        /**@deprecated */
+        /**@deprecated Has no effect: nothing reads it. */
         sync?: boolean;
     };
     /**

package/dist/game/nlcore/elements/type.d.ts

@@ -24,5 +24,10 @@ export type SoundPlayOptions = FadeOptions & {
     waitForEnd?: boolean;
 };
 export type ChainedActions = (Proxied<LogicAction.GameElement, Chained<LogicAction.Actions>> | LogicAction.Actions)[];
-export type ActionStatements = ChainedActions | string[];
+/**
+ * What a scene, a menu choice, a condition branch or a control block runs. Each entry is read on
+ * its own: an action or chained element runs as itself, and a plain string is a line of narration,
+ * so the two can sit side by side in one list.
+ */
+export type ActionStatements = (ChainedActions[number] | string)[];
 export type { TransitionAnimationType, TransitionTask, };

package/dist/game/player/elements/image/Image.d.ts

@@ -1,10 +1,76 @@
 import { Image as GameImage } from "../../../nlcore/elements/displayable/image";
 import React from "react";
 import { GameState } from "../../gameState";
+import { ElementProp, TransitionTask } from "../../../nlcore/elements/transition/type";
 export type ImageEvents = {
     "event:image.onLoad": [];
 };
+/** A laid-out size, in CSS pixels. */
+export type GroupSize = {
+    width: number;
+    height: number;
+};
+/**
+ * Where a transition puts a group that does not size the box: on the very pixels it will cover
+ * once it is the image at rest. `null` means exactly where a picture at rest sits.
+ *
+ * The box takes the sizing group's size, and the wrapper around it is placed by a layout anchor (a
+ * percentage of the stage, measured from the top - or from the bottom on an inverted axis) plus a
+ * `translate` of half its own size. The stage is scaled by a non-integer factor, so these lengths
+ * fall between device pixels, and the browser snaps layout positions to the pixel grid while
+ * leaving translations where they are. A group of the box's size therefore sits in it exactly as
+ * an image at rest does - by layout, on its corner, with no transform of its own - and comes out
+ * on the same pixels. That is the common case (two backgrounds of one size, a picture fading into
+ * itself, a character's expressions), and adding anything to it, even a translate of nothing, can
+ * change how a scaled wrapper's content is sampled.
+ *
+ * A group of another size has to make up the difference inside the box, and how it does so decides
+ * what the browser draws. Centred by layout (`top: 50%`, a flex box, auto margins), or by a
+ * transform alone, it lands within a pixel of its resting place but on the other side of a
+ * rounding; it is drawn resampled at a slightly different offset, and when the transition ends and
+ * the box takes its size, the whole picture steps by a fraction of a pixel and changes sharpness.
+ * So the difference is split the way the wrapper will split it at rest. On an axis anchored at the
+ * top or left the wrapper's layout position does not depend on its size: the group sits on that
+ * edge of the box and a translate moves it by half the size difference - the half the wrapper's own
+ * translate stops adding once the box has the group's size. On an inverted axis the wrapper is
+ * anchored at its bottom or right edge, so its layout position moves with its size: the group sits
+ * on that edge instead, which puts its layout position where the wrapper's will be, and the
+ * translate takes the other half back. Every length that gets snapped is then one that will be
+ * snapped at rest, and the unsnapped ones add up to the translate the wrapper will carry.
+ *
+ * Under a wrapper that also scales or rotates, the browser drops the fraction of the wrapper's own
+ * layout position before transforming, so on an inverted axis a group of another size can still be
+ * sampled a little differently from the way it will be at rest; it is never displaced.
+ *
+ * Transitions that move a group write the independent `translate` property, which composes with
+ * this.
+ */
+export declare function transitionGroupPlacement(box: GroupSize, own: GroupSize, invertX: boolean, invertY: boolean): React.CSSProperties | null;
 export declare function stackStyle(darkness: number): React.CSSProperties;
+/**
+ * The props each group of a running transition sits on, index-aligned with the transition's
+ * resolvers; a resolver's own frame is merged over them.
+ *
+ * The group that sizes the box stays exactly as it is at rest, and every other group the transition
+ * shows sits where it will rest once it sizes the box itself (see `transitionGroupPlacement`), so
+ * neither moves, nor changes how it is sampled, when the transition starts or when it ends. A
+ * group whose size is not known yet has not loaded and shows nothing; it is placed as at rest until
+ * it has. A keyed resolver drives a picture - a stack wrapper on the layered path - and an unkeyed
+ * one drives an element of the transition's own (ThroughColor's colour frame), centred over the box
+ * and gone once the transition ends.
+ *
+ * None of these names a `src`: each side's resolver carries its own. A base that named one would
+ * point the outgoing picture somewhere else for the moment between the two writes, which is long
+ * enough for the browser to drop the decoded picture and paint a frame without it.
+ */
+export declare function transitionGroupProps(resolve: TransitionTask<HTMLImageElement, any>["resolve"], options: {
+    layered: boolean;
+    darkness: number;
+    invertX: boolean;
+    invertY: boolean;
+    /** The laid-out size of each group, index-aligned with `resolve`, where it is known. */
+    sizes: (GroupSize | undefined)[];
+}): ElementProp<HTMLImageElement>[];
 declare function ImageComponent({ image, state, }: Readonly<{
     image: GameImage;
     state: GameState;

package/dist/game/player/gameState.d.ts

@@ -468,10 +468,10 @@ export declare class GameState {
     getStorable(): Storable;
     getSceneByName(name: string): Scene | null;
     getStory(): Story;
-    setInterval(callback: () => void, delay: number): NodeJS.Timeout;
-    clearInterval(interval: NodeJS.Timeout): void;
-    setTimeout(callback: () => void, delay: number): NodeJS.Timeout;
-    clearTimeout(timeout: NodeJS.Timeout): void;
+    setInterval(callback: () => void, delay: number): ReturnType<typeof setInterval>;
+    clearInterval(interval: ReturnType<typeof setInterval>): void;
+    setTimeout(callback: () => void, delay: number): ReturnType<typeof setTimeout>;
+    clearTimeout(timeout: ReturnType<typeof setTimeout>): void;
     forceAnimation(): Awaitable;
     /**
      * Mounts a new state to the game state manager