@moku-labs/game 0.15.29 → 0.15.31

package/dist/{src-wyJYr12n.mjs → src-5qdNjLKN.mjs}

@@ -8878,7 +8878,7 @@ function schemaOfType(type) {
 		defaults: notJson,
 		owned
 	};
-	const fields = {};
+	const fields = Object.create(null);
 	for (const [field, value] of Object.entries(defaults)) fields[field] = fieldKind(value);
 	return {
 		name,
@@ -32876,36 +32876,91 @@ function spriteOf(cctx, step) {
 function startTween(cctx, step) {
 	const entity = targetOf$2(cctx, step);
 	if (entity === void 0) return void 0;
-	return cctx.rt.start(entity, step.component, tweenTargetOf(cctx, entity, step), {
+	return cctx.rt.start(entity, step.component, inSpace(cctx, entity, step, step.to), trackOptionsOf$1(cctx, entity, step));
+}
+/**
+* The options a `tween` step starts its track with. The keyframe segments and the repeat are
+* passed only when the step has them, the segment targets turned like `to` in the root space.
+*
+* @param cctx - What the cursor carries down the tree.
+* @param entity - The entity the step moves.
+* @param step - The tween step.
+* @returns The track options.
+*/
+function trackOptionsOf$1(cctx, entity, step) {
+	const options = {
 		ms: step.ms,
 		ease: step.ease,
 		delayMs: step.delayMs,
 		additive: step.additive,
 		reduced: step.reduced
-	});
+	};
+	const segments = step.segments;
+	if (segments !== void 0) options.segments = step.space === "root" ? segments.map((segment) => ({
+		...segment,
+		to: inSpace(cctx, entity, step, segment.to)
+	})) : segments;
+	if (step.repeat !== void 0) options.repeat = step.repeat;
+	return options;
 }
 /**
-* The target fields of a `tween` step for one entity: as written in the local space, turned into
-* the space of the entity's parent in the root space.
+* Target fields of a `tween` step for one entity: as written in the local space, turned into the
+* space of the entity's parent in the root space.
 *
 * @param cctx - What the cursor carries down the tree.
 * @param entity - The entity the step moves.
 * @param step - The tween step.
+* @param fields - Its `to`, the target of one of its segments, or where it lands.
 * @returns The fields the track or the write aims at.
 */
-function tweenTargetOf(cctx, entity, step) {
-	if (step.space === "root") return cctx.rt.toLocal(entity, step.component, step.to);
-	return { ...step.to };
+function inSpace(cctx, entity, step, fields) {
+	if (step.space === "root") return cctx.rt.toLocal(entity, step.component, fields);
+	return { ...fields };
+}
+/**
+* The last value each field reaches over a list of segments.
+*
+* @param segments - The segments of a step.
+* @returns One value per field any segment names.
+* @example
+* ```ts
+* lastValues([{ at: 0.5, to: { y: 10, rotation: 2 } }, { at: 1, to: { y: 0 } }]); // { y: 0, rotation: 2 }
+* ```
+*/
+function lastValues$1(segments) {
+	const values = {};
+	for (const segment of segments) Object.assign(values, segment.to);
+	return values;
+}
+/**
+* Where a `tween` step that never started lands when it is finished: its target, and for a
+* keyframe walk every field its segments name too, at the last value they give it. A step that
+* repeats forever lands on its start pose, where it already stands, and an additive walk names
+* offsets that end with it: neither writes anything.
+*
+* @param step - The tween step.
+* @returns The fields to write, or `undefined` when the step writes nothing.
+*/
+function landingOf(step) {
+	if (step.repeat === "forever") return void 0;
+	if (step.segments === void 0) return step.to;
+	if (step.additive) return void 0;
+	return {
+		...lastValues$1(step.segments),
+		...step.to
+	};
 }
 /**
-* Writes the target of a `tween` step that never started, in the space the step names.
+* Writes where a `tween` step that never started lands, in the space the step names.
 *
 * @param cctx - What the cursor carries down the tree.
 * @param step - The tween step.
 */
 function writeTween(cctx, step) {
+	const landing = landingOf(step);
+	if (landing === void 0) return;
 	const entity = targetOf$2(cctx, step);
-	if (entity !== void 0) cctx.rt.write(entity, step.component, tweenTargetOf(cctx, entity, step));
+	if (entity !== void 0) cctx.rt.write(entity, step.component, inSpace(cctx, entity, step, landing));
 }
 /**
 * Writes the patch of a `set` step.
@@ -33126,7 +33181,9 @@ function advanceCursor(cctx, cursor, deltaMs) {
 /**
 * Ends one step at its own end: a track writes its exact target, a step that never started writes
 * it at once, the marks are jumped in tree order, no effect is fired and nothing is spawned: the
-* timeline despawns its entities as it ends, so a skipped spawn would only flash.
+* timeline despawns its entities as it ends, so a skipped spawn would only flash. A track that
+* repeats forever has no end: it lands on its start pose, and one that never started writes
+* nothing.
 *
 * @param cctx - What the cursor carries down the tree.
 * @param cursor - The cursor of the step.
@@ -34447,7 +34504,8 @@ function repeatsOf(repeat) {
 * keyframe segments walks them over `ms` and books every field they name; one with `repeat`
 * walks again when a run ends. With reduced motion on, every track but a loop takes 0 ms, its
 * delay and its repeats dropped: it lands on its target at its first frame step. A track started
-* with `reduced: "keep"` keeps its length, its delay and its repeats.
+* with `reduced: "keep"` keeps its length, its delay and its repeats. A timeline's loop under
+* reduced motion does not play at all: it is born ended, writes nothing, and its step goes on.
 *
 * @param actx - Domain context of the anim plugin.
 * @param entity - The entity to animate.
@@ -34462,9 +34520,11 @@ function startTrack$1(actx, entity, component, to, options, muted, driven = fals
 	const target = targetOf$1(to, options.segments);
 	const repeats = repeatsOf(options.repeat);
 	const keep = options.reduced === "keep";
-	const instant = actx.state.reducedMotion && !keep && repeats !== Number.POSITIVE_INFINITY;
+	const cut = actx.state.reducedMotion && !keep;
+	const instant = cut && repeats !== Number.POSITIVE_INFINITY;
 	const keys = keysOf(entity, component.componentName, target);
 	const names = Object.keys(target);
+	const bornEnded = names.length === 0 || cut && driven && repeats === Number.POSITIVE_INFINITY;
 	const track = {
 		id: actx.state.nextId,
 		entity,
@@ -34488,7 +34548,7 @@ function startTrack$1(actx, entity, component, to, options, muted, driven = fals
 		additive: options.additive === true,
 		driven,
 		bornFrame: actx.state.frame,
-		ended: names.length === 0,
+		ended: bornEnded,
 		segments: options.segments,
 		repeatsLeft: instant ? 0 : repeats,
 		held: false,
@@ -34593,7 +34653,7 @@ function advanceTrack(actx, track, deltaMs) {
 	const run = clock[1] ?? 0;
 	const fraction = track.ms <= 0 ? 1 : Math.min(run / track.ms, 1);
 	const final = fraction >= 1 && (track.repeatsLeft === 0 || track.ms <= 0);
-	if (!final && !track.driven && track.repeatsLeft === Number.POSITIVE_INFINITY && actx.state.loopsHeld?.(track.entity, track.reveals) === true) return 0;
+	if (isHeldLoop(actx, track, final)) return 0;
 	clock[1] = fraction;
 	writeFields(actx, track, final);
 	if (!final) return 0;
@@ -34601,15 +34661,29 @@ function advanceTrack(actx, track, deltaMs) {
 	return Math.max(0, run - track.ms);
 }
 /**
-* Writes the exact target of a track and ends it. Muted fields are left alone here too.
+* Tells whether an endless loop writes nothing this frame because the player cannot see it.
+*
+* @param actx - Domain context of the anim plugin.
+* @param track - The track that advances.
+* @param final - Whether this step lands the track.
+* @returns True when the loop is held.
+*/
+function isHeldLoop(actx, track, final) {
+	return !final && track.repeatsLeft === Number.POSITIVE_INFINITY && actx.state.loopsHeld?.(track.entity, track.reveals) === true;
+}
+/**
+* Writes the exact target of a track and ends it. Muted fields are left alone here too. A
+* timeline's loop has no end to land on: it lands on its first key, the pose its walk starts
+* from, which is where a cut or a fast walk leaves it (F75).
 *
 * @param actx - Domain context of the anim plugin.
 * @param track - The track to finish.
 */
 function finishTrack(actx, track) {
 	if (track.ended) return;
-	track.clock[1] = 1;
-	writeFields(actx, track, true);
+	const final = !track.driven || track.repeatsLeft !== Number.POSITIVE_INFINITY;
+	track.clock[1] = final ? 1 : 0;
+	writeFields(actx, track, final);
 	endTrack(actx, track);
 }
 /**
@@ -49843,6 +49917,102 @@ function createHandlers$1(ctx) {
 	} };
 }
 //#endregion
+//#region src/plugins/anim/timeline/checks.ts
+/**
+* Checks the keyframe segments of a `tween` step: at least one, every `at` in 0..1, each after the
+* one before, and the last at 1, because `to` is where the walk lands.
+*
+* @param component - Name of the component the step drives, for the error.
+* @param segments - The segments the author gave.
+* @throws {Error} When the list is empty, an `at` is out of range or out of order, or the last
+*   segment ends before 1.
+* @example
+* ```ts
+* checkSegments("Transform", [{ at: 0.5 }, { at: 1 }]); // returns; [{ at: 0.5 }] throws
+* ```
+*/
+function checkSegments(component, segments) {
+	if (segments.length === 0) throw new Error(`[game] A tween of ${component} has no segments.\n  Give it at least one segment, the last one at 1.`);
+	let previous = Number.NEGATIVE_INFINITY;
+	for (const { at } of segments) {
+		if (Number.isNaN(at) || at < 0 || at > 1) throw new Error(`[game] A tween of ${component} has a segment at ${at}.\n  Keep every at between 0 and 1.`);
+		if (at <= previous) throw new Error(`[game] A tween of ${component} has its segments out of order at ${at}.\n  Sort the segments by at, each one after the one before.`);
+		previous = at;
+	}
+	if (previous !== 1) throw new Error(`[game] A tween of ${component} ends its last segment at ${previous}.\n  End the last segment at 1: to is where the walk lands.`);
+}
+/**
+* Checks the space of a keyframe walk: an additive one names offsets, and the root space would
+* turn each offset as if it were a root position, so a chest under a slot at root y 500 would jump
+* by about 500 at its first segment. An additive walk stays in the local space.
+*
+* @param component - Name of the component the step drives, for the error.
+* @param additive - Whether the walk adds offsets.
+* @param space - The space the step names.
+* @throws {Error} When an additive walk names the root space.
+* @example
+* ```ts
+* checkWalkSpace("Transform", true, "local"); // returns; (…, true, "root") throws
+* ```
+*/
+function checkWalkSpace(component, additive, space) {
+	if (!additive || space === "local") return;
+	throw new Error(`[game] An additive tween of ${component} walks segments in the root space.\n  Use space "local" for an additive walk.`);
+}
+/**
+* Checks the repeat of a `tween` step: a whole number of extra runs, 0 or more, or `"forever"`.
+*
+* @param component - Name of the component the step drives, for the error.
+* @param repeat - The repeat the author gave.
+* @throws {Error} When the repeat is negative, not whole or not a number.
+* @example
+* ```ts
+* checkRepeat("Transform", "forever"); // returns; checkRepeat("Transform", 1.5) throws
+* ```
+*/
+function checkRepeat(component, repeat) {
+	if (repeat === "forever" || Number.isInteger(repeat) && repeat >= 0) return;
+	throw new Error(`[game] A tween of ${component} has repeat ${repeat}.\n  Give repeat a whole number of extra runs, 0 or more, or "forever".`);
+}
+/**
+* Tells whether a step never ends by itself: a `tween` that repeats forever, a `parallel` or a
+* `sequence` that holds one, and a `use` of one. Only a cancel or a finish ends it.
+*
+* @param step - The step to look into.
+* @returns True when the step never ends by itself.
+* @example
+* ```ts
+* neverEnds(wait(100)); // false
+* neverEnds(tween(1_048_576, Transform, { y: 0 }, { ms: 2400, repeat: "forever" })); // true
+* ```
+*/
+function neverEnds(step) {
+	switch (step.kind) {
+		case "tween": return step.repeat === "forever";
+		case "sequence":
+		case "parallel": return step.steps.some((child) => neverEnds(child));
+		case "use": return neverEnds(step.step);
+		default: return false;
+	}
+}
+/**
+* Checks the children of a `sequence`: a child that never ends may only be the last one, since
+* the children after it would never play. A `parallel` takes one anywhere.
+*
+* @param steps - The children, in order.
+* @throws {Error} When a child that never ends has another child after it.
+* @example
+* ```ts
+* checkSequence([wait(100), mark("landed")]); // returns; a forever tween before the mark throws
+* ```
+*/
+function checkSequence(steps) {
+	for (let index = 0; index < steps.length - 1; index++) {
+		const step = steps[index];
+		if (step !== void 0 && neverEnds(step)) throw new Error(`[game] Step ${index + 1} of a sequence never ends, so the steps after it would never play.\n  Put the forever step last, or run it in a parallel.`);
+	}
+}
+//#endregion
 //#region src/plugins/anim/timeline/steps.ts
 /**
 * Every haptic tick `haptic(kind)` takes, in one frozen list: the three impacts, the selection
@@ -49943,10 +50113,13 @@ function slotsJson(slots) {
 }
 /**
 * Runs the steps one after another. The remainder past a step's end reaches the next step in the
-* same frame, so the tree takes exactly the sum of its durations.
+* same frame, so the tree takes exactly the sum of its durations. A step that never ends (a
+* `tween` with `repeat: "forever"`, or a `parallel`, `sequence` or `use` that holds one) may only
+* come last: the steps after it would never play.
 *
 * @param steps - The steps, in order.
 * @returns The sequence step.
+* @throws {Error} When a step that never ends has another step after it.
 * @example
 * ```ts
 * sequence(wait(100), mark("done"));
@@ -49954,6 +50127,7 @@ function slotsJson(slots) {
 * ```
 */
 function sequence(...steps) {
+	checkSequence(steps);
 	return Object.freeze({
 		kind: "sequence",
 		steps: Object.freeze([...steps])
@@ -50026,6 +50200,28 @@ function mark(name) {
 	});
 }
 /**
+* Copies one keyframe segment into frozen plain data: its `at`, its ease when it names one and
+* its numeric target fields.
+*
+* @param segment - The segment the author gave.
+* @param segment.at - Where it ends, as a fraction of the track's `ms`.
+* @param segment.ease - Its curve; the step's `ease` when left out.
+* @param segment.to - The fields it reaches.
+* @returns A frozen copy.
+* @example
+* ```ts
+* frozenSegment({ at: 1, to: { y: 0, texture: "a" } }); // { at: 1, to: { y: 0 } }
+* ```
+*/
+function frozenSegment(segment) {
+	const frozen = {
+		at: segment.at,
+		to: Object.freeze(numbersOf(segment.to))
+	};
+	if (segment.ease !== void 0) frozen.ease = segment.ease;
+	return Object.freeze(frozen);
+}
+/**
 * Moves the numeric fields of one component of one target to an exact target value. The component
 * is any handle `world.ecs` takes, so the kit's `Sprite` and `NineSlice` of `defineGame` pass as
 * they are.
@@ -50033,10 +50229,12 @@ function mark(name) {
 * By default the fields are local: they are written into the target's own `Transform`. With
 * `space: "root"` the `x`, `y`, `rotation` and `scale` of a `Transform` are a root pose, the space
 * `at()` answers in, and are turned into the space of the target's `Parent` when the track starts.
-* That aims a hosted view, such as a board item inside the board slot, at another element. A
-* field the step does not name stays where it is, so under a turned parent name `x` and `y`
-* together. A target without a parent, and a component other than `Transform`, move as in the
-* local space.
+* That aims a hosted view at another element: an order's board item inside the scaled board slot
+* flies onto the order card with `{ x: at(card).x, y: at(card).y, scale: at(card).scale }` in the
+* root space, covers the card at the card's size, and its `Transform` stays slot-local. A field
+* the step does not name stays where it is, so under a turned parent name `x` and `y` together. A
+* target without a parent, and a component other than `Transform`, move as in the local space. An
+* additive walk names offsets, so it stays in the local space.
 *
 * @param target - The projection key or the entity to animate.
 * @param component - The component to animate.
@@ -50049,30 +50247,34 @@ function mark(name) {
 * @param options.space - `"root"` reads the `Transform` fields as a root pose; `"local"` when
 *   omitted.
 * @param options.reduced - `"keep"` plays the track at its length under reduced motion, a fade
-*   for one; `"cut"` (the default) lands it at once.
-* @returns The tween step.
-* @example
-* ```ts
-* // An order is delivered: the board item flies out of the scaled board slot onto the order card.
-* const deliverFly = defineAnimation("orders.deliverFly", {
-*   slots: { item: type<Target>(), card: type<Target>() },
-*   build: ({ item, card }, { at }) =>
-*     tween(item, Transform, { x: at(card).x, y: at(card).y, scale: at(card).scale }, {
-*       ms: 400, ease: "inCubic", space: "root"
-*     })
-* });
-* app.anim.play(deliverFly, {
-*   item: { projection: "board.items", key: "i1" },
-*   card: { projection: "hud", key: "card0" }
-* });
-* // 400 ms later the item covers the card at the card's size; its Transform stays slot-local
+*   for one; `"cut"` (the default) lands it at once, and a `"forever"` track does not play.
+* @param options.segments - Keyframe segments `{ at, ease?, to }` walked one after another over
+*   `ms` on one clock; a field a segment does not name holds, `to` is where the last one ends. An
+*   additive walk names offsets. The same as `TweenOptions` of `ViewHandle.tween`.
+* @param options.repeat - How many more times the walk runs, or `"forever"`: the step never ends
+*   by itself, so it comes last in a `sequence`.
+* @returns The tween step; `segments` and `repeat` are in it only when given.
+* @throws {Error} When the segments are empty, an `at` is outside 0..1 or out of order, the last
+*   segment ends before 1, an additive walk names the root space, or the repeat is not a whole
+*   number of 0 or more.
+* @example
+* ```ts
+* // A ready chest (entity 1048576) hops 14 up and back every 2.4 s, as offsets over its pose.
+* const chestBounce = defineAnimation("board.chestBounce", { slots: { chest: type<Target>() },
+*   build: ({ chest }) => tween(chest, Transform, { y: 0, scale: 0 }, { ms: 2400, additive: true,
+*     repeat: "forever", segments: [{ at: 0.08, ease: "out", to: { y: -14, scale: 0.06 } },
+*       { at: 0.22, ease: "in", to: { y: 0, scale: 0 } }, { at: 1, to: { y: 0, scale: 0 } }] }) });
+* const bounce = res(AnimPlayer).play(chestBounce, { chest: 1_048_576 });
+* // 192 ms later the chest stands 14 higher, its scale 0.06 larger; it bounces until cancelled
+* bounce.cancel(); // it stands on its own pose again
 * ```
 */
 function tween(target, component, to, options) {
-	return Object.freeze({
+	const erased = asComponent(component);
+	const step = {
 		kind: "tween",
 		target,
-		component: asComponent(component),
+		component: erased,
 		to: Object.freeze(numbersOf(to)),
 		ms: options.ms,
 		ease: options.ease ?? "out",
@@ -50080,7 +50282,17 @@ function tween(target, component, to, options) {
 		additive: options.additive === true,
 		space: options.space ?? "local",
 		reduced: options.reduced ?? "cut"
-	});
+	};
+	if (options.segments !== void 0) {
+		checkSegments(erased.componentName, options.segments);
+		checkWalkSpace(erased.componentName, step.additive, step.space);
+		step.segments = Object.freeze(options.segments.map((segment) => frozenSegment(segment)));
+	}
+	if (options.repeat !== void 0) {
+		checkRepeat(erased.componentName, options.repeat);
+		step.repeat = options.repeat;
+	}
+	return Object.freeze(step);
 }
 /**
 * Writes a component patch at once. Any field may be written, not only the numeric ones. The

package/dist/testing.d.mts

@@ -1,6 +1,6 @@
 import { $n as FeaturePlugin, Dr as Json, dr as Descriptor, gr as NodeFx, hr as Hint, sr as NodeTable, tr as AnyFlow, xr as FakeClock, yr as ClockSource } from "./types-D27I4Q7b.mjs";
-import { t as createApp } from "./index-Cl5zwodk.mjs";
-import { b as saveOf, v as WithGameState, y as memory } from "./types-Cyu_jKop.mjs";
+import { t as createApp } from "./index-DMeqKGSu.mjs";
+import { b as saveOf, v as WithGameState, y as memory } from "./types-DmU_qlvA.mjs";
 import { a as createHeadless, i as ReproResult, n as HeadlessGame, o as runRepro, r as Repro, s as stepFrames, t as HeadlessApp } from "./headless-f31cEZ7f.mjs";
 import { AnyPluginInstance } from "@moku-labs/core";
 

package/dist/testing.mjs

@@ -1,4 +1,4 @@
-import { en as refuseStart, in as type, m as flattenFeatures, t as createApp, tn as exit } from "./src-wyJYr12n.mjs";
+import { en as refuseStart, in as type, m as flattenFeatures, t as createApp, tn as exit } from "./src-5qdNjLKN.mjs";
 import { n as saveOf, t as memory } from "./memory-CWlqhS7l.mjs";
 import { t as fakeClock } from "./fake-6mazmHK3.mjs";
 import { i as stepFrames, r as runRepro, t as createHeadless } from "./headless-Bxxl_mQX.mjs";

package/dist/{types-DjQkfbfZ.d.mts → types-DHamyZq1.d.mts}

@@ -207,10 +207,13 @@ type StepMotion = MotionHandle & {
 declare const HAPTIC_KINDS: readonly ["light", "medium", "heavy", "selection", "success", "warning", "error"];
 /**
  * Runs the steps one after another. The remainder past a step's end reaches the next step in the
- * same frame, so the tree takes exactly the sum of its durations.
+ * same frame, so the tree takes exactly the sum of its durations. A step that never ends (a
+ * `tween` with `repeat: "forever"`, or a `parallel`, `sequence` or `use` that holds one) may only
+ * come last: the steps after it would never play.
  *
  * @param steps - The steps, in order.
  * @returns The sequence step.
+ * @throws {Error} When a step that never ends has another step after it.
  * @example
  * ```ts
  * sequence(wait(100), mark("done"));
@@ -275,10 +278,12 @@ declare function mark(name: string): Step;
  * By default the fields are local: they are written into the target's own `Transform`. With
  * `space: "root"` the `x`, `y`, `rotation` and `scale` of a `Transform` are a root pose, the space
  * `at()` answers in, and are turned into the space of the target's `Parent` when the track starts.
- * That aims a hosted view, such as a board item inside the board slot, at another element. A
- * field the step does not name stays where it is, so under a turned parent name `x` and `y`
- * together. A target without a parent, and a component other than `Transform`, move as in the
- * local space.
+ * That aims a hosted view at another element: an order's board item inside the scaled board slot
+ * flies onto the order card with `{ x: at(card).x, y: at(card).y, scale: at(card).scale }` in the
+ * root space, covers the card at the card's size, and its `Transform` stays slot-local. A field
+ * the step does not name stays where it is, so under a turned parent name `x` and `y` together. A
+ * target without a parent, and a component other than `Transform`, move as in the local space. An
+ * additive walk names offsets, so it stays in the local space.
  *
  * @param target - The projection key or the entity to animate.
  * @param component - The component to animate.
@@ -291,23 +296,26 @@ declare function mark(name: string): Step;
  * @param options.space - `"root"` reads the `Transform` fields as a root pose; `"local"` when
  *   omitted.
  * @param options.reduced - `"keep"` plays the track at its length under reduced motion, a fade
- *   for one; `"cut"` (the default) lands it at once.
- * @returns The tween step.
- * @example
- * ```ts
- * // An order is delivered: the board item flies out of the scaled board slot onto the order card.
- * const deliverFly = defineAnimation("orders.deliverFly", {
- *   slots: { item: type<Target>(), card: type<Target>() },
- *   build: ({ item, card }, { at }) =>
- *     tween(item, Transform, { x: at(card).x, y: at(card).y, scale: at(card).scale }, {
- *       ms: 400, ease: "inCubic", space: "root"
- *     })
- * });
- * app.anim.play(deliverFly, {
- *   item: { projection: "board.items", key: "i1" },
- *   card: { projection: "hud", key: "card0" }
- * });
- * // 400 ms later the item covers the card at the card's size; its Transform stays slot-local
+ *   for one; `"cut"` (the default) lands it at once, and a `"forever"` track does not play.
+ * @param options.segments - Keyframe segments `{ at, ease?, to }` walked one after another over
+ *   `ms` on one clock; a field a segment does not name holds, `to` is where the last one ends. An
+ *   additive walk names offsets. The same as `TweenOptions` of `ViewHandle.tween`.
+ * @param options.repeat - How many more times the walk runs, or `"forever"`: the step never ends
+ *   by itself, so it comes last in a `sequence`.
+ * @returns The tween step; `segments` and `repeat` are in it only when given.
+ * @throws {Error} When the segments are empty, an `at` is outside 0..1 or out of order, the last
+ *   segment ends before 1, an additive walk names the root space, or the repeat is not a whole
+ *   number of 0 or more.
+ * @example
+ * ```ts
+ * // A ready chest (entity 1048576) hops 14 up and back every 2.4 s, as offsets over its pose.
+ * const chestBounce = defineAnimation("board.chestBounce", { slots: { chest: type<Target>() },
+ *   build: ({ chest }) => tween(chest, Transform, { y: 0, scale: 0 }, { ms: 2400, additive: true,
+ *     repeat: "forever", segments: [{ at: 0.08, ease: "out", to: { y: -14, scale: 0.06 } },
+ *       { at: 0.22, ease: "in", to: { y: 0, scale: 0 } }, { at: 1, to: { y: 0, scale: 0 } }] }) });
+ * const bounce = res(AnimPlayer).play(chestBounce, { chest: 1_048_576 });
+ * // 192 ms later the chest stands 14 higher, its scale 0.06 larger; it bounces until cancelled
+ * bounce.cancel(); // it stands on its own pose again
  * ```
  */
 declare function tween<Value extends object>(target: Target, component: ComponentHandle<Value>, to: Partial<NumericFields<Value>>, options: {
@@ -317,6 +325,12 @@ declare function tween<Value extends object>(target: Target, component: Componen
   additive?: boolean;
   space?: "local" | "root";
   reduced?: ReducedMotion;
+  segments?: readonly {
+    at: number;
+    ease?: Ease;
+    to: Partial<NumericFields<Value>>;
+  }[];
+  repeat?: number | "forever";
 }): Step;
 /**
  * Writes a component patch at once. Any field may be written, not only the numeric ones. The
@@ -658,6 +672,16 @@ type Step = {
   readonly additive: boolean; /** `"root"`: the `Transform` fields are a root pose, turned local when the track starts. */
   readonly space: "local" | "root"; /** `"keep"`: reduced motion plays the track as written; `"cut"` lands it at once. */
   readonly reduced: ReducedMotion;
+  /**
+   * The keyframe segments the track walks over `ms`, frozen; only on a step built with them.
+   * In the root space each segment's target is turned local when the track starts, like `to`.
+   */
+  readonly segments?: readonly TrackSegment[];
+  /**
+   * The runs after the first one, or `"forever"` for a step that never ends by itself; only on
+   * a step built with it.
+   */
+  readonly repeat?: number | "forever";
 } | {
   readonly kind: "set";
   readonly target: Target;

package/dist/{types-Cyu_jKop.d.mts → types-DmU_qlvA.d.mts}

@@ -1,7 +1,7 @@
 import { $ as PixiModule, $n as FeaturePlugin, Dr as Json, Lr as SnapshotOf, Mr as PlayerStateProvider, Nr as ProviderCall, Pr as SaveDoc, Tr as Config, X as Config$2, a as Config$3, d as Manifest, lt as Orientation, n as AssetsIo, tr as AnyFlow, ur as TypeTag, xr as FakeClock, yr as ClockSource, zn as Config$1 } from "./types-D27I4Q7b.mjs";
-import { o as AudioContextLike, s as Config$4 } from "./types-DjQkfbfZ.mjs";
+import { o as AudioContextLike, s as Config$4 } from "./types-DHamyZq1.mjs";
 import { R as I18nApi, U as StringTable, W as TextKey } from "./types-BAp9HdR4.mjs";
-import { St as effectsPlugin, Tt as audioPlugin, ht as PlatformProvider, i as screen, pt as platformPlugin, t as createApp } from "./index-Cl5zwodk.mjs";
+import { St as effectsPlugin, Tt as audioPlugin, ht as PlatformProvider, i as screen, pt as platformPlugin, t as createApp } from "./index-DMeqKGSu.mjs";
 import { AnyPluginInstance } from "@moku-labs/core";
 
 //#region src/plugins/model/store/providers/memory.d.ts

package/dist/{visual-DhNLNtl8.d.mts → visual-HGn_TF2x.d.mts}

@@ -1,9 +1,9 @@
 import { Vr as Api$3, Y as Api, nn as Api$1, wr as Api$2 } from "./types-D27I4Q7b.mjs";
-import { P as AnimApi, r as UiApi } from "./types-DjQkfbfZ.mjs";
+import { P as AnimApi, r as UiApi } from "./types-DHamyZq1.mjs";
 import { N as InputApi } from "./types-BAp9HdR4.mjs";
 import { r as Repro } from "./headless-f31cEZ7f.mjs";
 import { a as InputOf, r as ControlApp } from "./types-CgE5L_7f.mjs";
-import { t as commands } from "./commands-BOxMqhVe.mjs";
+import { t as commands } from "./commands-C8N_rpwt.mjs";
 
 //#region src/visual/types.d.ts
 /** The base commands of the `/control` door, keyed by their short names. */

package/dist/visual.d.mts

@@ -1,2 +1,2 @@
-import { a as VisualApp, c as VisualRenderer, d as VisualStart, f as VisualStep, h as VisualTolerance, i as CheckpointResult, l as VisualReport, m as VisualTestResult, n as runVisualTests, o as VisualOptions, p as VisualTest, r as defineVisualTest, s as VisualPage, t as parseVisualArgv, u as VisualSetup } from "./visual-DhNLNtl8.mjs";
+import { a as VisualApp, c as VisualRenderer, d as VisualStart, f as VisualStep, h as VisualTolerance, i as CheckpointResult, l as VisualReport, m as VisualTestResult, n as runVisualTests, o as VisualOptions, p as VisualTest, r as defineVisualTest, s as VisualPage, t as parseVisualArgv, u as VisualSetup } from "./visual-HGn_TF2x.mjs";
 export { type CheckpointResult, type VisualApp, type VisualOptions, type VisualPage, type VisualRenderer, type VisualReport, type VisualSetup, type VisualStart, type VisualStep, type VisualTest, type VisualTestResult, type VisualTolerance, defineVisualTest, parseVisualArgv, runVisualTests };

package/dist/visual.mjs

@@ -1,5 +1,5 @@
-import { n as read, t as sources } from "./sources-ncFMQIus.mjs";
-import { n as commands, t as run } from "./run-DRcc2SKF.mjs";
+import { n as read, t as sources } from "./sources-DM5Zcl4o.mjs";
+import { n as commands, t as run } from "./run-BnriyKUu.mjs";
 import path from "node:path";
 import { createBrandConsole } from "@moku-labs/common/cli";
 import { mkdir, readFile, writeFile } from "node:fs/promises";