@reactor-models/fast-h3 1.0.2 → 1.3.0

package/dist/core.d.mts

@@ -2,7 +2,7 @@ import { FileRef, Reactor } from '@reactor-team/js-sdk';
 export { FileRef } from '@reactor-team/js-sdk';
 
 declare const MODEL_NAME: "reactor/fast-h3";
-declare const MODEL_VERSION: "v1.0.2";
+declare const MODEL_VERSION: "v1.3.0";
 /**
  * Preset media tracks for the FastH3 model.
  *
@@ -21,7 +21,7 @@ declare const FastH3Tracks: readonly [{
 }];
 /** Track names the client can subscribe to (recvonly, from the client's perspective). */
 type FastH3RecvTrackName = "main_video" | "main_audio";
-/** Remove one clip by its UUID from whichever queue holds it, freeing its slot. Works on generating and built clips alike; a build already running for it is discarded when it completes. The clip that is playing is in neither queue — `stop` is the command that cuts it. A built clip stays in `queue_update.history` after popping, so clips continued from it are unaffected; an unbuilt clip that queued clips continue from is refused, since popping it would leave them nothing to open from — pop those first. Emits `clip_popped`, `queue_update` and `state_update`, or `command_error` when no queued clip has that id or queued clips still continue from it. */
+/** Remove one clip by its UUID from whichever queue holds it, freeing its slot. Works on generating and built clips alike; a build already running for it is discarded when it completes. The clip that is playing is in neither queue — `stop` is the command that cuts it. A built clip stays in `queue_update.history` after popping, so clips referencing its frame are unaffected; an unbuilt clip that queued clips reference is refused, since popping it would leave them without an endpoint — pop those first. Emits `clip_popped`, `queue_update` and `state_update`, or `command_error` when no queued clip has that id or queued clips still reference its last frame. */
 interface FastH3PopParams {
     /**
      * UUID of the queued clip to remove, from `clip_queued` or `queue_update`.
@@ -51,7 +51,7 @@ interface FastH3PlayParams {
      */
     clip_id?: string;
 }
-/** Queue one clip generation. The clip enters the generation queue (at `position`, or the back), builds when its turn comes, and then joins the back of the playout queue, announced by `clip_generated`. The prompt is what the clip will show; the metadata is an opaque string echoed back on every message that references the clip, for frontends to carry their own tracking data. The clip opens from text alone, from an uploaded still (`starting_frame` — the image animates forward), or from an existing clip's last frame (`continue_from_clip_id` — any clip in the queues or in `queue_update.history`); a continued clip simply waits its turn until its source is built, wherever the two sit in the queue. The clip's canvas is the session's; its length is the `seconds` passed here (snapped to what the model can produce) or the session default, and its seed is the one passed here or the session's advancing default. Builds run through the queue in order; watch `queue_update` for the clip turning ready. Replies `clip_queued` with the clip's UUID and emits `queue_update` and `state_update`, or `command_error` when the queue is full, the prompt is empty, both a starting frame and a source clip are given, the source clip is unknown or no longer retained, or the upload is not a decodable image. */
+/** Queue one clip generation. The clip enters the generation queue (at `position`, or the back), builds when its turn comes, and then joins the back of the playout queue, announced by `clip_generated`. The prompt is what the clip will show; the metadata is an opaque string echoed back on every message that references the clip, for frontends to carry their own tracking data. The clip opens from text alone, from an uploaded still (`starting_frame` — the image animates forward), or from an existing clip's last frame (`continue_from_clip_id` — any clip in the queues or in `queue_update.history`); a continued clip simply waits its turn until its source is built, wherever the two sit in the queue. An uploaded `ending_frame` or a generated clip's clean last frame (`ending_from_clip_id`) can accompany any opener — or stand alone — to make the clip animate *into* and close on that image. Set both clip-id fields to the same UUID to leave and return to one generated frame. The clip's canvas is the session's; its length is the `seconds` passed here (snapped to what the model can produce) or the session default, and its seed is the one passed here or the session's advancing default. Builds run through the queue in order; watch `queue_update` for the clip turning ready. Replies `clip_queued` with the clip's UUID and emits `queue_update` and `state_update`, or `command_error` when the queue is full, the prompt is empty, both a starting frame and a source clip are given, both ending conditions are given, a source clip is unknown or no longer retained, or an upload is not a decodable image. */
 interface FastH3EnqueueParams {
     /**
      * Seed for this clip. Omitted or null, the session's default is used and advances by one; passing a seed leaves the default untouched, so explicit and automatic seeding do not interfere.
@@ -60,8 +60,8 @@ interface FastH3EnqueueParams {
      */
     seed?: number | null;
     /**
-     * What the clip should show, up to 800 characters. Fixed once enqueued; a different scene is a new `enqueue`.
-     * @maxLength 800
+     * What the clip should show, up to 4000 characters. Fixed once enqueued; a different scene is a new `enqueue`.
+     * @maxLength 4000
      * @default ""
      */
     prompt?: string;
@@ -84,11 +84,21 @@ interface FastH3EnqueueParams {
      * @default null
      */
     position?: number | null;
+    /**
+     * A still image the clip animates into and closes on — its last frame. Common formats decode; the frame is fitted to the session canvas. Combine it with a `starting_frame` (or a `continue_from_clip_id` opener) for first-and-last generation, or send it alone to fix only the ending. Omit for a clip with no fixed end or one ending on a retained generated frame. At most one of this and `ending_from_clip_id`; independent of how the clip opens, so it pairs with either opener.
+     * @default null
+     */
+    ending_frame?: FileRef | null;
     /**
      * A still image the clip opens from and animates forward — image-to-video. Common formats decode; the frame is fitted to the session canvas. To continue from a video, extract the frame you want and send it here. Omit for a clip opening from text or from another clip; at most one of this and `continue_from_clip_id`.
      * @default null
      */
     starting_frame?: FileRef | null;
+    /**
+     * UUID of the clip whose clean retained last frame this clip animates into and closes on. Any clip in either queue or in `queue_update.history` qualifies, including one that has not built yet: this clip then waits for it. Blank for no generated ending target; at most one of this and `ending_frame`. This is independent of the opener, so it may equal `continue_from_clip_id` to create a hold that starts and ends on the same generated frame.
+     * @default ""
+     */
+    ending_from_clip_id?: string;
     /**
      * UUID of the clip whose last frame this one opens from and animates forward — how clips chain into a continuing scene. Any clip in either queue or in `queue_update.history` qualifies, including one that has not built yet: this clip then waits for it. Blank for a clip opening from text or from an uploaded frame; at most one of this and `starting_frame`.
      * @default ""
@@ -150,7 +160,9 @@ interface FastH3ClipMovedMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     };
     /** Which queue it moved within: `generation` or `playout`. */
@@ -174,7 +186,9 @@ interface FastH3ClipFailedMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     };
     /** What went wrong. */
@@ -196,7 +210,9 @@ interface FastH3ClipPoppedMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     };
 }
@@ -212,7 +228,9 @@ interface FastH3ClipQueuedMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     };
 }
@@ -228,7 +246,9 @@ interface FastH3ClipStartedMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     };
 }
@@ -248,7 +268,9 @@ interface FastH3ClipStoppedMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     };
     /** Seconds of video and audio sent since the session began. */
@@ -261,7 +283,7 @@ interface FastH3ClipStoppedMessage {
  */
 interface FastH3QueueUpdateMessage {
     type: "queue_update";
-    /** Built clips no longer queued — played, stopped, or popped — whose last frame is still retained, oldest first. No longer playable (`play` refuses them), but any can be named in `enqueue`'s `continue_from_clip_id`; the oldest are evicted as new builds finish, so the front of this list is what expires next. */
+    /** Built clips no longer queued — played, stopped, or popped — whose last frame is still retained, oldest first. No longer playable (`play` refuses them), but any can be named in `enqueue`'s `continue_from_clip_id` or `ending_from_clip_id`; the oldest are evicted as new builds finish, so the front of this list is what expires next. */
     history: {
         "seed": number;
         "ready": boolean;
@@ -270,7 +292,9 @@ interface FastH3QueueUpdateMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     }[];
     /** Built clips waiting to play, front first. A finished build joins at the back; bare `play` (and autoplay) takes the front; `move` reorders; playing or `pop` consumes. */
@@ -282,10 +306,12 @@ interface FastH3QueueUpdateMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     }[];
-    /** Clips waiting to build, front first. Builds consume this queue from the front, one at a time, pausing only while `playout` is at capacity; a clip whose `continue_from_clip_id` source is not built yet is skipped until it is, without blocking the rest. `enqueue`'s `position` and `move` control the order. */
+    /** Clips waiting to build, front first. Builds consume this queue from the front, one at a time, pausing only while `playout` is at capacity; a clip whose referenced starting or ending source is not built yet is skipped until it is, without blocking the rest. `enqueue`'s `position` and `move` control the order. */
     generation: {
         "seed": number;
         "ready": boolean;
@@ -294,7 +320,9 @@ interface FastH3QueueUpdateMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     }[];
 }
@@ -358,7 +386,9 @@ interface FastH3ClipFinishedMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     };
     /** Seconds of video and audio sent since the session began, this clip included. */
@@ -406,7 +436,9 @@ interface FastH3ClipGeneratedMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     };
 }
@@ -468,8 +500,8 @@ declare class FastH3Model extends Reactor {
     /** @deprecated The model client now extends `Reactor` directly — call methods on `this` instead. This accessor returns `this` for backwards compatibility and will be removed in a future major release. */
     get reactor(): this;
     /**
-     * Remove one clip by its UUID from whichever queue holds it, freeing its slot. Works on generating and built clips alike; a build already running for it is discarded when it completes. The clip that is playing is in neither queue — `stop` is the command that cuts it. A built clip stays in `queue_update.history` after popping, so clips continued from it are unaffected; an unbuilt clip that queued clips continue from is refused, since popping it would leave them nothing to open from — pop those first. Emits `clip_popped`, `queue_update` and `state_update`, or `command_error` when no queued clip has that id or queued clips still continue from it.
-     * @param params - Remove one clip by its UUID from whichever queue holds it, freeing its slot. Works on generating and built clips alike; a build already running for it is discarded when it completes. The clip that is playing is in neither queue — `stop` is the command that cuts it. A built clip stays in `queue_update.history` after popping, so clips continued from it are unaffected; an unbuilt clip that queued clips continue from is refused, since popping it would leave them nothing to open from — pop those first. Emits `clip_popped`, `queue_update` and `state_update`, or `command_error` when no queued clip has that id or queued clips still continue from it.
+     * Remove one clip by its UUID from whichever queue holds it, freeing its slot. Works on generating and built clips alike; a build already running for it is discarded when it completes. The clip that is playing is in neither queue — `stop` is the command that cuts it. A built clip stays in `queue_update.history` after popping, so clips referencing its frame are unaffected; an unbuilt clip that queued clips reference is refused, since popping it would leave them without an endpoint — pop those first. Emits `clip_popped`, `queue_update` and `state_update`, or `command_error` when no queued clip has that id or queued clips still reference its last frame.
+     * @param params - Remove one clip by its UUID from whichever queue holds it, freeing its slot. Works on generating and built clips alike; a build already running for it is discarded when it completes. The clip that is playing is in neither queue — `stop` is the command that cuts it. A built clip stays in `queue_update.history` after popping, so clips referencing its frame are unaffected; an unbuilt clip that queued clips reference is refused, since popping it would leave them without an endpoint — pop those first. Emits `clip_popped`, `queue_update` and `state_update`, or `command_error` when no queued clip has that id or queued clips still reference its last frame.
      * @returns The correlated {@link FastH3ClipPoppedMessage} reply, or `undefined` when the send fails (the SDK never rejects — see `getLastError()`).
      */
     pop(params: FastH3PopParams): Promise<FastH3ClipPoppedMessage | undefined>;
@@ -496,8 +528,8 @@ declare class FastH3Model extends Reactor {
      */
     reset(): Promise<FastH3SessionResetMessage | undefined>;
     /**
-     * Queue one clip generation. The clip enters the generation queue (at `position`, or the back), builds when its turn comes, and then joins the back of the playout queue, announced by `clip_generated`. The prompt is what the clip will show; the metadata is an opaque string echoed back on every message that references the clip, for frontends to carry their own tracking data. The clip opens from text alone, from an uploaded still (`starting_frame` — the image animates forward), or from an existing clip's last frame (`continue_from_clip_id` — any clip in the queues or in `queue_update.history`); a continued clip simply waits its turn until its source is built, wherever the two sit in the queue. The clip's canvas is the session's; its length is the `seconds` passed here (snapped to what the model can produce) or the session default, and its seed is the one passed here or the session's advancing default. Builds run through the queue in order; watch `queue_update` for the clip turning ready. Replies `clip_queued` with the clip's UUID and emits `queue_update` and `state_update`, or `command_error` when the queue is full, the prompt is empty, both a starting frame and a source clip are given, the source clip is unknown or no longer retained, or the upload is not a decodable image.
-     * @param params - Queue one clip generation. The clip enters the generation queue (at `position`, or the back), builds when its turn comes, and then joins the back of the playout queue, announced by `clip_generated`. The prompt is what the clip will show; the metadata is an opaque string echoed back on every message that references the clip, for frontends to carry their own tracking data. The clip opens from text alone, from an uploaded still (`starting_frame` — the image animates forward), or from an existing clip's last frame (`continue_from_clip_id` — any clip in the queues or in `queue_update.history`); a continued clip simply waits its turn until its source is built, wherever the two sit in the queue. The clip's canvas is the session's; its length is the `seconds` passed here (snapped to what the model can produce) or the session default, and its seed is the one passed here or the session's advancing default. Builds run through the queue in order; watch `queue_update` for the clip turning ready. Replies `clip_queued` with the clip's UUID and emits `queue_update` and `state_update`, or `command_error` when the queue is full, the prompt is empty, both a starting frame and a source clip are given, the source clip is unknown or no longer retained, or the upload is not a decodable image.
+     * Queue one clip generation. The clip enters the generation queue (at `position`, or the back), builds when its turn comes, and then joins the back of the playout queue, announced by `clip_generated`. The prompt is what the clip will show; the metadata is an opaque string echoed back on every message that references the clip, for frontends to carry their own tracking data. The clip opens from text alone, from an uploaded still (`starting_frame` — the image animates forward), or from an existing clip's last frame (`continue_from_clip_id` — any clip in the queues or in `queue_update.history`); a continued clip simply waits its turn until its source is built, wherever the two sit in the queue. An uploaded `ending_frame` or a generated clip's clean last frame (`ending_from_clip_id`) can accompany any opener — or stand alone — to make the clip animate *into* and close on that image. Set both clip-id fields to the same UUID to leave and return to one generated frame. The clip's canvas is the session's; its length is the `seconds` passed here (snapped to what the model can produce) or the session default, and its seed is the one passed here or the session's advancing default. Builds run through the queue in order; watch `queue_update` for the clip turning ready. Replies `clip_queued` with the clip's UUID and emits `queue_update` and `state_update`, or `command_error` when the queue is full, the prompt is empty, both a starting frame and a source clip are given, both ending conditions are given, a source clip is unknown or no longer retained, or an upload is not a decodable image.
+     * @param params - Queue one clip generation. The clip enters the generation queue (at `position`, or the back), builds when its turn comes, and then joins the back of the playout queue, announced by `clip_generated`. The prompt is what the clip will show; the metadata is an opaque string echoed back on every message that references the clip, for frontends to carry their own tracking data. The clip opens from text alone, from an uploaded still (`starting_frame` — the image animates forward), or from an existing clip's last frame (`continue_from_clip_id` — any clip in the queues or in `queue_update.history`); a continued clip simply waits its turn until its source is built, wherever the two sit in the queue. An uploaded `ending_frame` or a generated clip's clean last frame (`ending_from_clip_id`) can accompany any opener — or stand alone — to make the clip animate *into* and close on that image. Set both clip-id fields to the same UUID to leave and return to one generated frame. The clip's canvas is the session's; its length is the `seconds` passed here (snapped to what the model can produce) or the session default, and its seed is the one passed here or the session's advancing default. Builds run through the queue in order; watch `queue_update` for the clip turning ready. Replies `clip_queued` with the clip's UUID and emits `queue_update` and `state_update`, or `command_error` when the queue is full, the prompt is empty, both a starting frame and a source clip are given, both ending conditions are given, a source clip is unknown or no longer retained, or an upload is not a decodable image.
      * @returns The correlated {@link FastH3ClipQueuedMessage} reply, or `undefined` when the send fails (the SDK never rejects — see `getLastError()`).
      */
     enqueue(params: FastH3EnqueueParams): Promise<FastH3ClipQueuedMessage | undefined>;
@@ -508,7 +540,7 @@ declare class FastH3Model extends Reactor {
      */
     setSeed(params: FastH3SetSeedParams): Promise<FastH3SeedAcceptedMessage | undefined>;
     /**
-     * Return both queues' contents — `generation` (waiting to build) and `playout` (built, playable) — plus `history`, the built clips no longer queued that `continue_from_clip_id` can still name, every clip as its full structure. The same payload the model broadcasts as `queue_update`. Valid at any time.
+     * Return both queues' contents — `generation` (waiting to build) and `playout` (built, playable) — plus `history`, the built clips no longer queued that `continue_from_clip_id` or `ending_from_clip_id` can still name, every clip as its full structure. The same payload the model broadcasts as `queue_update`. Valid at any time.
      * @returns The correlated {@link FastH3QueueUpdateMessage} reply, or `undefined` when the send fails (the SDK never rejects — see `getLastError()`).
      */
     getQueue(): Promise<FastH3QueueUpdateMessage | undefined>;

package/dist/core.d.ts

@@ -2,7 +2,7 @@ import { FileRef, Reactor } from '@reactor-team/js-sdk';
 export { FileRef } from '@reactor-team/js-sdk';
 
 declare const MODEL_NAME: "reactor/fast-h3";
-declare const MODEL_VERSION: "v1.0.2";
+declare const MODEL_VERSION: "v1.3.0";
 /**
  * Preset media tracks for the FastH3 model.
  *
@@ -21,7 +21,7 @@ declare const FastH3Tracks: readonly [{
 }];
 /** Track names the client can subscribe to (recvonly, from the client's perspective). */
 type FastH3RecvTrackName = "main_video" | "main_audio";
-/** Remove one clip by its UUID from whichever queue holds it, freeing its slot. Works on generating and built clips alike; a build already running for it is discarded when it completes. The clip that is playing is in neither queue — `stop` is the command that cuts it. A built clip stays in `queue_update.history` after popping, so clips continued from it are unaffected; an unbuilt clip that queued clips continue from is refused, since popping it would leave them nothing to open from — pop those first. Emits `clip_popped`, `queue_update` and `state_update`, or `command_error` when no queued clip has that id or queued clips still continue from it. */
+/** Remove one clip by its UUID from whichever queue holds it, freeing its slot. Works on generating and built clips alike; a build already running for it is discarded when it completes. The clip that is playing is in neither queue — `stop` is the command that cuts it. A built clip stays in `queue_update.history` after popping, so clips referencing its frame are unaffected; an unbuilt clip that queued clips reference is refused, since popping it would leave them without an endpoint — pop those first. Emits `clip_popped`, `queue_update` and `state_update`, or `command_error` when no queued clip has that id or queued clips still reference its last frame. */
 interface FastH3PopParams {
     /**
      * UUID of the queued clip to remove, from `clip_queued` or `queue_update`.
@@ -51,7 +51,7 @@ interface FastH3PlayParams {
      */
     clip_id?: string;
 }
-/** Queue one clip generation. The clip enters the generation queue (at `position`, or the back), builds when its turn comes, and then joins the back of the playout queue, announced by `clip_generated`. The prompt is what the clip will show; the metadata is an opaque string echoed back on every message that references the clip, for frontends to carry their own tracking data. The clip opens from text alone, from an uploaded still (`starting_frame` — the image animates forward), or from an existing clip's last frame (`continue_from_clip_id` — any clip in the queues or in `queue_update.history`); a continued clip simply waits its turn until its source is built, wherever the two sit in the queue. The clip's canvas is the session's; its length is the `seconds` passed here (snapped to what the model can produce) or the session default, and its seed is the one passed here or the session's advancing default. Builds run through the queue in order; watch `queue_update` for the clip turning ready. Replies `clip_queued` with the clip's UUID and emits `queue_update` and `state_update`, or `command_error` when the queue is full, the prompt is empty, both a starting frame and a source clip are given, the source clip is unknown or no longer retained, or the upload is not a decodable image. */
+/** Queue one clip generation. The clip enters the generation queue (at `position`, or the back), builds when its turn comes, and then joins the back of the playout queue, announced by `clip_generated`. The prompt is what the clip will show; the metadata is an opaque string echoed back on every message that references the clip, for frontends to carry their own tracking data. The clip opens from text alone, from an uploaded still (`starting_frame` — the image animates forward), or from an existing clip's last frame (`continue_from_clip_id` — any clip in the queues or in `queue_update.history`); a continued clip simply waits its turn until its source is built, wherever the two sit in the queue. An uploaded `ending_frame` or a generated clip's clean last frame (`ending_from_clip_id`) can accompany any opener — or stand alone — to make the clip animate *into* and close on that image. Set both clip-id fields to the same UUID to leave and return to one generated frame. The clip's canvas is the session's; its length is the `seconds` passed here (snapped to what the model can produce) or the session default, and its seed is the one passed here or the session's advancing default. Builds run through the queue in order; watch `queue_update` for the clip turning ready. Replies `clip_queued` with the clip's UUID and emits `queue_update` and `state_update`, or `command_error` when the queue is full, the prompt is empty, both a starting frame and a source clip are given, both ending conditions are given, a source clip is unknown or no longer retained, or an upload is not a decodable image. */
 interface FastH3EnqueueParams {
     /**
      * Seed for this clip. Omitted or null, the session's default is used and advances by one; passing a seed leaves the default untouched, so explicit and automatic seeding do not interfere.
@@ -60,8 +60,8 @@ interface FastH3EnqueueParams {
      */
     seed?: number | null;
     /**
-     * What the clip should show, up to 800 characters. Fixed once enqueued; a different scene is a new `enqueue`.
-     * @maxLength 800
+     * What the clip should show, up to 4000 characters. Fixed once enqueued; a different scene is a new `enqueue`.
+     * @maxLength 4000
      * @default ""
      */
     prompt?: string;
@@ -84,11 +84,21 @@ interface FastH3EnqueueParams {
      * @default null
      */
     position?: number | null;
+    /**
+     * A still image the clip animates into and closes on — its last frame. Common formats decode; the frame is fitted to the session canvas. Combine it with a `starting_frame` (or a `continue_from_clip_id` opener) for first-and-last generation, or send it alone to fix only the ending. Omit for a clip with no fixed end or one ending on a retained generated frame. At most one of this and `ending_from_clip_id`; independent of how the clip opens, so it pairs with either opener.
+     * @default null
+     */
+    ending_frame?: FileRef | null;
     /**
      * A still image the clip opens from and animates forward — image-to-video. Common formats decode; the frame is fitted to the session canvas. To continue from a video, extract the frame you want and send it here. Omit for a clip opening from text or from another clip; at most one of this and `continue_from_clip_id`.
      * @default null
      */
     starting_frame?: FileRef | null;
+    /**
+     * UUID of the clip whose clean retained last frame this clip animates into and closes on. Any clip in either queue or in `queue_update.history` qualifies, including one that has not built yet: this clip then waits for it. Blank for no generated ending target; at most one of this and `ending_frame`. This is independent of the opener, so it may equal `continue_from_clip_id` to create a hold that starts and ends on the same generated frame.
+     * @default ""
+     */
+    ending_from_clip_id?: string;
     /**
      * UUID of the clip whose last frame this one opens from and animates forward — how clips chain into a continuing scene. Any clip in either queue or in `queue_update.history` qualifies, including one that has not built yet: this clip then waits for it. Blank for a clip opening from text or from an uploaded frame; at most one of this and `starting_frame`.
      * @default ""
@@ -150,7 +160,9 @@ interface FastH3ClipMovedMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     };
     /** Which queue it moved within: `generation` or `playout`. */
@@ -174,7 +186,9 @@ interface FastH3ClipFailedMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     };
     /** What went wrong. */
@@ -196,7 +210,9 @@ interface FastH3ClipPoppedMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     };
 }
@@ -212,7 +228,9 @@ interface FastH3ClipQueuedMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     };
 }
@@ -228,7 +246,9 @@ interface FastH3ClipStartedMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     };
 }
@@ -248,7 +268,9 @@ interface FastH3ClipStoppedMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     };
     /** Seconds of video and audio sent since the session began. */
@@ -261,7 +283,7 @@ interface FastH3ClipStoppedMessage {
  */
 interface FastH3QueueUpdateMessage {
     type: "queue_update";
-    /** Built clips no longer queued — played, stopped, or popped — whose last frame is still retained, oldest first. No longer playable (`play` refuses them), but any can be named in `enqueue`'s `continue_from_clip_id`; the oldest are evicted as new builds finish, so the front of this list is what expires next. */
+    /** Built clips no longer queued — played, stopped, or popped — whose last frame is still retained, oldest first. No longer playable (`play` refuses them), but any can be named in `enqueue`'s `continue_from_clip_id` or `ending_from_clip_id`; the oldest are evicted as new builds finish, so the front of this list is what expires next. */
     history: {
         "seed": number;
         "ready": boolean;
@@ -270,7 +292,9 @@ interface FastH3QueueUpdateMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     }[];
     /** Built clips waiting to play, front first. A finished build joins at the back; bare `play` (and autoplay) takes the front; `move` reorders; playing or `pop` consumes. */
@@ -282,10 +306,12 @@ interface FastH3QueueUpdateMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     }[];
-    /** Clips waiting to build, front first. Builds consume this queue from the front, one at a time, pausing only while `playout` is at capacity; a clip whose `continue_from_clip_id` source is not built yet is skipped until it is, without blocking the rest. `enqueue`'s `position` and `move` control the order. */
+    /** Clips waiting to build, front first. Builds consume this queue from the front, one at a time, pausing only while `playout` is at capacity; a clip whose referenced starting or ending source is not built yet is skipped until it is, without blocking the rest. `enqueue`'s `position` and `move` control the order. */
     generation: {
         "seed": number;
         "ready": boolean;
@@ -294,7 +320,9 @@ interface FastH3QueueUpdateMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     }[];
 }
@@ -358,7 +386,9 @@ interface FastH3ClipFinishedMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     };
     /** Seconds of video and audio sent since the session began, this clip included. */
@@ -406,7 +436,9 @@ interface FastH3ClipGeneratedMessage {
         "clip_id": string;
         "seconds": number;
         "metadata": string;
+        "has_ending_frame"?: boolean;
         "has_starting_frame": boolean;
+        "ending_from_clip_id"?: string | null;
         "continue_from_clip_id": string | null;
     };
 }
@@ -468,8 +500,8 @@ declare class FastH3Model extends Reactor {
     /** @deprecated The model client now extends `Reactor` directly — call methods on `this` instead. This accessor returns `this` for backwards compatibility and will be removed in a future major release. */
     get reactor(): this;
     /**
-     * Remove one clip by its UUID from whichever queue holds it, freeing its slot. Works on generating and built clips alike; a build already running for it is discarded when it completes. The clip that is playing is in neither queue — `stop` is the command that cuts it. A built clip stays in `queue_update.history` after popping, so clips continued from it are unaffected; an unbuilt clip that queued clips continue from is refused, since popping it would leave them nothing to open from — pop those first. Emits `clip_popped`, `queue_update` and `state_update`, or `command_error` when no queued clip has that id or queued clips still continue from it.
-     * @param params - Remove one clip by its UUID from whichever queue holds it, freeing its slot. Works on generating and built clips alike; a build already running for it is discarded when it completes. The clip that is playing is in neither queue — `stop` is the command that cuts it. A built clip stays in `queue_update.history` after popping, so clips continued from it are unaffected; an unbuilt clip that queued clips continue from is refused, since popping it would leave them nothing to open from — pop those first. Emits `clip_popped`, `queue_update` and `state_update`, or `command_error` when no queued clip has that id or queued clips still continue from it.
+     * Remove one clip by its UUID from whichever queue holds it, freeing its slot. Works on generating and built clips alike; a build already running for it is discarded when it completes. The clip that is playing is in neither queue — `stop` is the command that cuts it. A built clip stays in `queue_update.history` after popping, so clips referencing its frame are unaffected; an unbuilt clip that queued clips reference is refused, since popping it would leave them without an endpoint — pop those first. Emits `clip_popped`, `queue_update` and `state_update`, or `command_error` when no queued clip has that id or queued clips still reference its last frame.
+     * @param params - Remove one clip by its UUID from whichever queue holds it, freeing its slot. Works on generating and built clips alike; a build already running for it is discarded when it completes. The clip that is playing is in neither queue — `stop` is the command that cuts it. A built clip stays in `queue_update.history` after popping, so clips referencing its frame are unaffected; an unbuilt clip that queued clips reference is refused, since popping it would leave them without an endpoint — pop those first. Emits `clip_popped`, `queue_update` and `state_update`, or `command_error` when no queued clip has that id or queued clips still reference its last frame.
      * @returns The correlated {@link FastH3ClipPoppedMessage} reply, or `undefined` when the send fails (the SDK never rejects — see `getLastError()`).
      */
     pop(params: FastH3PopParams): Promise<FastH3ClipPoppedMessage | undefined>;
@@ -496,8 +528,8 @@ declare class FastH3Model extends Reactor {
      */
     reset(): Promise<FastH3SessionResetMessage | undefined>;
     /**
-     * Queue one clip generation. The clip enters the generation queue (at `position`, or the back), builds when its turn comes, and then joins the back of the playout queue, announced by `clip_generated`. The prompt is what the clip will show; the metadata is an opaque string echoed back on every message that references the clip, for frontends to carry their own tracking data. The clip opens from text alone, from an uploaded still (`starting_frame` — the image animates forward), or from an existing clip's last frame (`continue_from_clip_id` — any clip in the queues or in `queue_update.history`); a continued clip simply waits its turn until its source is built, wherever the two sit in the queue. The clip's canvas is the session's; its length is the `seconds` passed here (snapped to what the model can produce) or the session default, and its seed is the one passed here or the session's advancing default. Builds run through the queue in order; watch `queue_update` for the clip turning ready. Replies `clip_queued` with the clip's UUID and emits `queue_update` and `state_update`, or `command_error` when the queue is full, the prompt is empty, both a starting frame and a source clip are given, the source clip is unknown or no longer retained, or the upload is not a decodable image.
-     * @param params - Queue one clip generation. The clip enters the generation queue (at `position`, or the back), builds when its turn comes, and then joins the back of the playout queue, announced by `clip_generated`. The prompt is what the clip will show; the metadata is an opaque string echoed back on every message that references the clip, for frontends to carry their own tracking data. The clip opens from text alone, from an uploaded still (`starting_frame` — the image animates forward), or from an existing clip's last frame (`continue_from_clip_id` — any clip in the queues or in `queue_update.history`); a continued clip simply waits its turn until its source is built, wherever the two sit in the queue. The clip's canvas is the session's; its length is the `seconds` passed here (snapped to what the model can produce) or the session default, and its seed is the one passed here or the session's advancing default. Builds run through the queue in order; watch `queue_update` for the clip turning ready. Replies `clip_queued` with the clip's UUID and emits `queue_update` and `state_update`, or `command_error` when the queue is full, the prompt is empty, both a starting frame and a source clip are given, the source clip is unknown or no longer retained, or the upload is not a decodable image.
+     * Queue one clip generation. The clip enters the generation queue (at `position`, or the back), builds when its turn comes, and then joins the back of the playout queue, announced by `clip_generated`. The prompt is what the clip will show; the metadata is an opaque string echoed back on every message that references the clip, for frontends to carry their own tracking data. The clip opens from text alone, from an uploaded still (`starting_frame` — the image animates forward), or from an existing clip's last frame (`continue_from_clip_id` — any clip in the queues or in `queue_update.history`); a continued clip simply waits its turn until its source is built, wherever the two sit in the queue. An uploaded `ending_frame` or a generated clip's clean last frame (`ending_from_clip_id`) can accompany any opener — or stand alone — to make the clip animate *into* and close on that image. Set both clip-id fields to the same UUID to leave and return to one generated frame. The clip's canvas is the session's; its length is the `seconds` passed here (snapped to what the model can produce) or the session default, and its seed is the one passed here or the session's advancing default. Builds run through the queue in order; watch `queue_update` for the clip turning ready. Replies `clip_queued` with the clip's UUID and emits `queue_update` and `state_update`, or `command_error` when the queue is full, the prompt is empty, both a starting frame and a source clip are given, both ending conditions are given, a source clip is unknown or no longer retained, or an upload is not a decodable image.
+     * @param params - Queue one clip generation. The clip enters the generation queue (at `position`, or the back), builds when its turn comes, and then joins the back of the playout queue, announced by `clip_generated`. The prompt is what the clip will show; the metadata is an opaque string echoed back on every message that references the clip, for frontends to carry their own tracking data. The clip opens from text alone, from an uploaded still (`starting_frame` — the image animates forward), or from an existing clip's last frame (`continue_from_clip_id` — any clip in the queues or in `queue_update.history`); a continued clip simply waits its turn until its source is built, wherever the two sit in the queue. An uploaded `ending_frame` or a generated clip's clean last frame (`ending_from_clip_id`) can accompany any opener — or stand alone — to make the clip animate *into* and close on that image. Set both clip-id fields to the same UUID to leave and return to one generated frame. The clip's canvas is the session's; its length is the `seconds` passed here (snapped to what the model can produce) or the session default, and its seed is the one passed here or the session's advancing default. Builds run through the queue in order; watch `queue_update` for the clip turning ready. Replies `clip_queued` with the clip's UUID and emits `queue_update` and `state_update`, or `command_error` when the queue is full, the prompt is empty, both a starting frame and a source clip are given, both ending conditions are given, a source clip is unknown or no longer retained, or an upload is not a decodable image.
      * @returns The correlated {@link FastH3ClipQueuedMessage} reply, or `undefined` when the send fails (the SDK never rejects — see `getLastError()`).
      */
     enqueue(params: FastH3EnqueueParams): Promise<FastH3ClipQueuedMessage | undefined>;
@@ -508,7 +540,7 @@ declare class FastH3Model extends Reactor {
      */
     setSeed(params: FastH3SetSeedParams): Promise<FastH3SeedAcceptedMessage | undefined>;
     /**
-     * Return both queues' contents — `generation` (waiting to build) and `playout` (built, playable) — plus `history`, the built clips no longer queued that `continue_from_clip_id` can still name, every clip as its full structure. The same payload the model broadcasts as `queue_update`. Valid at any time.
+     * Return both queues' contents — `generation` (waiting to build) and `playout` (built, playable) — plus `history`, the built clips no longer queued that `continue_from_clip_id` or `ending_from_clip_id` can still name, every clip as its full structure. The same payload the model broadcasts as `queue_update`. Valid at any time.
      * @returns The correlated {@link FastH3QueueUpdateMessage} reply, or `undefined` when the send fails (the SDK never rejects — see `getLastError()`).
      */
     getQueue(): Promise<FastH3QueueUpdateMessage | undefined>;

package/dist/core.js

@@ -29,7 +29,7 @@ __export(core_exports, {
 module.exports = __toCommonJS(core_exports);
 var import_js_sdk = require("@reactor-team/js-sdk");
 var MODEL_NAME = "reactor/fast-h3";
-var MODEL_VERSION = "v1.0.2";
+var MODEL_VERSION = "v1.3.0";
 var FastH3Tracks = [
   { name: "main_video", kind: "video", direction: "recvonly" },
   { name: "main_audio", kind: "audio", direction: "recvonly" }
@@ -54,8 +54,8 @@ var FastH3Model = class extends import_js_sdk.Reactor {
     return this;
   }
   /**
-   * Remove one clip by its UUID from whichever queue holds it, freeing its slot. Works on generating and built clips alike; a build already running for it is discarded when it completes. The clip that is playing is in neither queue — `stop` is the command that cuts it. A built clip stays in `queue_update.history` after popping, so clips continued from it are unaffected; an unbuilt clip that queued clips continue from is refused, since popping it would leave them nothing to open from — pop those first. Emits `clip_popped`, `queue_update` and `state_update`, or `command_error` when no queued clip has that id or queued clips still continue from it.
-   * @param params - Remove one clip by its UUID from whichever queue holds it, freeing its slot. Works on generating and built clips alike; a build already running for it is discarded when it completes. The clip that is playing is in neither queue — `stop` is the command that cuts it. A built clip stays in `queue_update.history` after popping, so clips continued from it are unaffected; an unbuilt clip that queued clips continue from is refused, since popping it would leave them nothing to open from — pop those first. Emits `clip_popped`, `queue_update` and `state_update`, or `command_error` when no queued clip has that id or queued clips still continue from it.
+   * Remove one clip by its UUID from whichever queue holds it, freeing its slot. Works on generating and built clips alike; a build already running for it is discarded when it completes. The clip that is playing is in neither queue — `stop` is the command that cuts it. A built clip stays in `queue_update.history` after popping, so clips referencing its frame are unaffected; an unbuilt clip that queued clips reference is refused, since popping it would leave them without an endpoint — pop those first. Emits `clip_popped`, `queue_update` and `state_update`, or `command_error` when no queued clip has that id or queued clips still reference its last frame.
+   * @param params - Remove one clip by its UUID from whichever queue holds it, freeing its slot. Works on generating and built clips alike; a build already running for it is discarded when it completes. The clip that is playing is in neither queue — `stop` is the command that cuts it. A built clip stays in `queue_update.history` after popping, so clips referencing its frame are unaffected; an unbuilt clip that queued clips reference is refused, since popping it would leave them without an endpoint — pop those first. Emits `clip_popped`, `queue_update` and `state_update`, or `command_error` when no queued clip has that id or queued clips still reference its last frame.
    * @returns The correlated {@link FastH3ClipPoppedMessage} reply, or `undefined` when the send fails (the SDK never rejects — see `getLastError()`).
    */
   async pop(params) {
@@ -97,8 +97,8 @@ var FastH3Model = class extends import_js_sdk.Reactor {
     return reply === void 0 ? void 0 : _unwrapMessage(reply);
   }
   /**
-   * Queue one clip generation. The clip enters the generation queue (at `position`, or the back), builds when its turn comes, and then joins the back of the playout queue, announced by `clip_generated`. The prompt is what the clip will show; the metadata is an opaque string echoed back on every message that references the clip, for frontends to carry their own tracking data. The clip opens from text alone, from an uploaded still (`starting_frame` — the image animates forward), or from an existing clip's last frame (`continue_from_clip_id` — any clip in the queues or in `queue_update.history`); a continued clip simply waits its turn until its source is built, wherever the two sit in the queue. The clip's canvas is the session's; its length is the `seconds` passed here (snapped to what the model can produce) or the session default, and its seed is the one passed here or the session's advancing default. Builds run through the queue in order; watch `queue_update` for the clip turning ready. Replies `clip_queued` with the clip's UUID and emits `queue_update` and `state_update`, or `command_error` when the queue is full, the prompt is empty, both a starting frame and a source clip are given, the source clip is unknown or no longer retained, or the upload is not a decodable image.
-   * @param params - Queue one clip generation. The clip enters the generation queue (at `position`, or the back), builds when its turn comes, and then joins the back of the playout queue, announced by `clip_generated`. The prompt is what the clip will show; the metadata is an opaque string echoed back on every message that references the clip, for frontends to carry their own tracking data. The clip opens from text alone, from an uploaded still (`starting_frame` — the image animates forward), or from an existing clip's last frame (`continue_from_clip_id` — any clip in the queues or in `queue_update.history`); a continued clip simply waits its turn until its source is built, wherever the two sit in the queue. The clip's canvas is the session's; its length is the `seconds` passed here (snapped to what the model can produce) or the session default, and its seed is the one passed here or the session's advancing default. Builds run through the queue in order; watch `queue_update` for the clip turning ready. Replies `clip_queued` with the clip's UUID and emits `queue_update` and `state_update`, or `command_error` when the queue is full, the prompt is empty, both a starting frame and a source clip are given, the source clip is unknown or no longer retained, or the upload is not a decodable image.
+   * Queue one clip generation. The clip enters the generation queue (at `position`, or the back), builds when its turn comes, and then joins the back of the playout queue, announced by `clip_generated`. The prompt is what the clip will show; the metadata is an opaque string echoed back on every message that references the clip, for frontends to carry their own tracking data. The clip opens from text alone, from an uploaded still (`starting_frame` — the image animates forward), or from an existing clip's last frame (`continue_from_clip_id` — any clip in the queues or in `queue_update.history`); a continued clip simply waits its turn until its source is built, wherever the two sit in the queue. An uploaded `ending_frame` or a generated clip's clean last frame (`ending_from_clip_id`) can accompany any opener — or stand alone — to make the clip animate *into* and close on that image. Set both clip-id fields to the same UUID to leave and return to one generated frame. The clip's canvas is the session's; its length is the `seconds` passed here (snapped to what the model can produce) or the session default, and its seed is the one passed here or the session's advancing default. Builds run through the queue in order; watch `queue_update` for the clip turning ready. Replies `clip_queued` with the clip's UUID and emits `queue_update` and `state_update`, or `command_error` when the queue is full, the prompt is empty, both a starting frame and a source clip are given, both ending conditions are given, a source clip is unknown or no longer retained, or an upload is not a decodable image.
+   * @param params - Queue one clip generation. The clip enters the generation queue (at `position`, or the back), builds when its turn comes, and then joins the back of the playout queue, announced by `clip_generated`. The prompt is what the clip will show; the metadata is an opaque string echoed back on every message that references the clip, for frontends to carry their own tracking data. The clip opens from text alone, from an uploaded still (`starting_frame` — the image animates forward), or from an existing clip's last frame (`continue_from_clip_id` — any clip in the queues or in `queue_update.history`); a continued clip simply waits its turn until its source is built, wherever the two sit in the queue. An uploaded `ending_frame` or a generated clip's clean last frame (`ending_from_clip_id`) can accompany any opener — or stand alone — to make the clip animate *into* and close on that image. Set both clip-id fields to the same UUID to leave and return to one generated frame. The clip's canvas is the session's; its length is the `seconds` passed here (snapped to what the model can produce) or the session default, and its seed is the one passed here or the session's advancing default. Builds run through the queue in order; watch `queue_update` for the clip turning ready. Replies `clip_queued` with the clip's UUID and emits `queue_update` and `state_update`, or `command_error` when the queue is full, the prompt is empty, both a starting frame and a source clip are given, both ending conditions are given, a source clip is unknown or no longer retained, or an upload is not a decodable image.
    * @returns The correlated {@link FastH3ClipQueuedMessage} reply, or `undefined` when the send fails (the SDK never rejects — see `getLastError()`).
    */
   async enqueue(params) {
@@ -115,7 +115,7 @@ var FastH3Model = class extends import_js_sdk.Reactor {
     return reply === void 0 ? void 0 : _unwrapMessage(reply);
   }
   /**
-   * Return both queues' contents — `generation` (waiting to build) and `playout` (built, playable) — plus `history`, the built clips no longer queued that `continue_from_clip_id` can still name, every clip as its full structure. The same payload the model broadcasts as `queue_update`. Valid at any time.
+   * Return both queues' contents — `generation` (waiting to build) and `playout` (built, playable) — plus `history`, the built clips no longer queued that `continue_from_clip_id` or `ending_from_clip_id` can still name, every clip as its full structure. The same payload the model broadcasts as `queue_update`. Valid at any time.
    * @returns The correlated {@link FastH3QueueUpdateMessage} reply, or `undefined` when the send fails (the SDK never rejects — see `getLastError()`).
    */
   async getQueue() {