@shotstack/shotstack-studio 2.16.3 → 2.18.0

package/dist/index.d.ts

@@ -1,4 +1,28 @@
 import { components } from '@shotstack/schemas';
+import { operations } from '@shotstack/schemas';
+
+/** Passed to the host handler for one generation. */
+export declare interface AssetGenerationRequest {
+    clipId: string;
+    /** Snapshot of the clip's asset when generation started. */
+    asset: Record<string, unknown>;
+    /**
+     * Signalled when the SDK stops waiting for this generation — the clip was removed, or the
+     * edit was reloaded or disposed. Cancel the underlying request if the provider supports it;
+     * otherwise ignore it and let the request finish. Either way the SDK discards the result.
+     */
+    signal: AbortSignal;
+}
+
+/** Resolves with the URL of the generated asset. */
+export declare type AssetGeneratorHandler = (request: AssetGenerationRequest) => Promise<{
+    url: string;
+}>;
+
+export declare interface AssetGeneratorOptions {
+    /** Model catalogue with each entry's option schema included. Entries without one are ignored. */
+    catalogue?: GenerationModelCatalogueResponse;
+}
 
 /**
  * Payload passed to button click handlers.
@@ -154,6 +178,7 @@ export declare class Edit {
     private timingManager;
     private lumaMaskController;
     private playerReconciler;
+    private assetGenerator;
     private outputSettings;
     private selectionManager;
     private commandHistory;
@@ -167,6 +192,11 @@ export declare class Edit {
     private isBatchingEvents;
     private isExporting;
     private lastResolved;
+    /**
+     * Clip removal reaches the generator the way it reaches the reconciler: from resolved state,
+     * once the mutation is committed. Bookkeeping only — emitting from here re-enters the command queue.
+     */
+    private readonly onResolvedForGeneration;
     /**
      * Create an Edit instance from a template configuration.
      */
@@ -200,6 +230,15 @@ export declare class Edit {
      * returned object has no effect on the edit — use `updateClipById` to make changes.
      */
     getClipById(clipId: string): Clip | null;
+    /**
+     * Register the handler that turns a prompt-bearing clip into a generated asset.
+     *
+     * The SDK owns the pending, generating and failed states and writes the returned
+     * URL back to the clip; the host owns how generation happens and what a failure
+     * message says. Without a handler, no generate affordance is shown.
+     */
+    registerAssetGenerator(handler: AssetGeneratorHandler, options?: AssetGeneratorOptions): void;
+    private applyGeneratedSrc;
     /**
      * Look up the (trackIndex, clipIndex) position of a clip by its stable ID.
      */
@@ -434,6 +473,7 @@ export declare class Edit {
     private findBestContentMatch;
     private lastClipClick;
     private static readonly DoubleClickThresholdMs;
+    private setupGenerationListeners;
     private setupIntentListeners;
 }
 
@@ -567,6 +607,8 @@ declare type EditEventMap = {
 
 declare type EventPayloadMap<TPayload = any> = Record<string, TPayload>;
 
+declare type GenerationModelCatalogueResponse = operations["getModels"]["responses"][200]["content"]["application/json"];
+
 declare type Listener<TPayload = any> = (payload: TPayload) => void;
 
 /**
@@ -639,6 +681,7 @@ export declare class Timeline {
     private readonly handlePlaybackPause;
     private readonly handleClipSelected;
     private readonly handleClipLoadFailed;
+    private readonly handleClipGeneration;
     private readonly handleClipUpdated;
     private readonly handleClipFocusChanged;
     private readonly handleRulerMouseMove;
@@ -715,7 +758,9 @@ export declare class UIController {
     /** Maximum total pixels for resolution picker (undefined = unlimited) */
     private readonly maxPixels?;
     private clipToolbar;
+    private generateToolbar;
     private toolbarMode;
+    private generationListeners;
     private currentAssetType;
     private currentTrackIndex;
     private currentClipIndex;
@@ -845,6 +890,15 @@ export declare class UIController {
      * Update toolbar visibility based on current mode and selection.
      */
     private updateToolbarVisibility;
+    private isGenerateModeAvailable;
+    /**
+     * The mode actually shown. `generate` is intent rather than state: selecting a clip
+     * that cannot be generated falls back to `asset` without discarding the choice, so
+     * returning to a generative clip lands back on generate.
+     */
+    private effectiveMode;
+    /** Queries the document because toolbar mode toggles mount outside this.container. */
+    private syncGenerateSegments;
     /**
      * Check if any toolbar is currently visible (clip is selected).
      */

package/dist/internal.d.ts

@@ -1,4 +1,28 @@
 import { components } from '@shotstack/schemas';
+import { operations } from '@shotstack/schemas';
+
+/** Passed to the host handler for one generation. */
+declare interface AssetGenerationRequest {
+    clipId: string;
+    /** Snapshot of the clip's asset when generation started. */
+    asset: Record<string, unknown>;
+    /**
+     * Signalled when the SDK stops waiting for this generation — the clip was removed, or the
+     * edit was reloaded or disposed. Cancel the underlying request if the provider supports it;
+     * otherwise ignore it and let the request finish. Either way the SDK discards the result.
+     */
+    signal: AbortSignal;
+}
+
+/** Resolves with the URL of the generated asset. */
+declare type AssetGeneratorHandler = (request: AssetGenerationRequest) => Promise<{
+    url: string;
+}>;
+
+declare interface AssetGeneratorOptions {
+    /** Model catalogue with each entry's option schema included. Entries without one are ignored. */
+    catalogue?: GenerationModelCatalogueResponse;
+}
 
 declare type Clip = components["schemas"]["Clip"];
 
@@ -43,6 +67,7 @@ export declare class Edit {
     private timingManager;
     private lumaMaskController;
     private playerReconciler;
+    private assetGenerator;
     private outputSettings;
     private selectionManager;
     private commandHistory;
@@ -56,6 +81,11 @@ export declare class Edit {
     private isBatchingEvents;
     private isExporting;
     private lastResolved;
+    /**
+     * Clip removal reaches the generator the way it reaches the reconciler: from resolved state,
+     * once the mutation is committed. Bookkeeping only — emitting from here re-enters the command queue.
+     */
+    private readonly onResolvedForGeneration;
     /**
      * Create an Edit instance from a template configuration.
      */
@@ -89,6 +119,15 @@ export declare class Edit {
      * returned object has no effect on the edit — use `updateClipById` to make changes.
      */
     getClipById(clipId: string): Clip | null;
+    /**
+     * Register the handler that turns a prompt-bearing clip into a generated asset.
+     *
+     * The SDK owns the pending, generating and failed states and writes the returned
+     * URL back to the clip; the host owns how generation happens and what a failure
+     * message says. Without a handler, no generate affordance is shown.
+     */
+    registerAssetGenerator(handler: AssetGeneratorHandler, options?: AssetGeneratorOptions): void;
+    private applyGeneratedSrc;
     /**
      * Look up the (trackIndex, clipIndex) position of a clip by its stable ID.
      */
@@ -323,6 +362,7 @@ export declare class Edit {
     private findBestContentMatch;
     private lastClipClick;
     private static readonly DoubleClickThresholdMs;
+    private setupGenerationListeners;
     private setupIntentListeners;
 }
 
@@ -461,6 +501,8 @@ declare class EventEmitter<TEventPayloadMap extends EventPayloadMap = EventPaylo
 
 declare type EventPayloadMap<TPayload = any> = Record<string, TPayload>;
 
+declare type GenerationModelCatalogueResponse = operations["getModels"]["responses"][200]["content"]["application/json"];
+
 /**
  * Thrown by mutation methods (addClip, addTrack, addFont, setFonts) when a
  * referenced asset/font URL fails preflight.