@cesdk/node 1.77.0-nightly.20260612 → 1.77.0-rc.0

package/index.d.mts

@@ -6684,6 +6684,12 @@ declare class CreativeEngine {
     event: EventAPI;
     scene: SceneAPI;
     variable: VariableAPI;
+    /**
+     * Register, run, and discover named, overridable actions. On headless Node the registry
+     * starts with only the engine-default `ly.img.*` actions (no host UI), but the API is
+     * identical to the browser engine.
+     */
+    actions: EngineActions;
     version: string;
 
     /**
@@ -8099,6 +8105,97 @@ export declare type EffectTypeLonghand = `//ly.img.ubq/effect/${EffectTypeShorth
 /** @public */
 export declare type EffectTypeShorthand = (typeof EFFECT_TYPES)[number];
 
+/** @public Known action ids from {@link EngineActionsRegistry}. */
+export declare type EngineActionId = keyof EngineActionsRegistry & string;
+
+/** @public Info about a registered action, from {@link EngineActions.list}. */
+export declare interface EngineActionInfo {
+    /** The action id, e.g. `nudge`. */
+    id: string;
+    /** Whether the action currently says it can run. */
+    enabled: boolean;
+    /** Optional JSON description of the arguments it accepts. */
+    argSchema: string | null;
+}
+
+/**
+ * @public Named, overridable actions for one engine. Actions are either JS
+ * closures you register or engine defaults (e.g. undo/redo), and
+ * either kind can override the other by reusing the id.
+ *
+ * JS-registered actions run directly in JS, so on the web you get full fidelity:
+ * {@link get} hands back the raw function and {@link run} passes args/results by
+ * reference (non-serializable payloads like File/Blob work). The engine also keeps
+ * a JSON trampoline per action so defaults run natively and host actions stay
+ * reachable across the FFI — that path is JSON-only and async. Engine defaults you
+ * have not overridden are reachable only via {@link run}; {@link get} returns undefined.
+ *
+ * @remarks Main-thread only. {@link get} is web-only; use run/has/list cross-platform.
+ */
+export declare class EngineActions {
+    #private;
+
+    /**
+     * Register an action, replacing any existing one with the same id.
+     *
+     * @param id - The action id (e.g. `undo`). Reusing an engine default's id overrides it.
+     * @param fn - The action body (sync or async). On the web it runs directly with
+     *   any JS values. Across the FFI args/results are JSON, so only serializable
+     *   payloads work there.
+     */
+    register<K extends EngineActionId>(id: K, fn: EngineActionsRegistry[K] extends (...args: any[]) => any ? EngineActionsRegistry[K] : EngineCustomActionFunction): void;
+    register(id: string, fn: EngineCustomActionFunction): void;
+    /**
+     * Get the raw registered function for an id so you can call it synchronously.
+     *
+     * Returns the exact function you registered. Returns `undefined` for unknown ids
+     * and engine-default native actions (which have no JS function) — use {@link run}
+     * for those.
+     *
+     * @remarks Web-only.
+     */
+    get<K extends EngineActionId>(id: K): EngineActionsRegistry[K] | undefined;
+    get(id: string): EngineCustomActionFunction | undefined;
+    /**
+     * Run an action by id and return its result as a Promise.
+     *
+     * JS-registered actions are called directly (args/result by reference). Engine
+     * defaults go across the FFI (JSON args/result).
+     *
+     * @param id - The action id.
+     * @param args - Arguments forwarded to the action.
+     * @returns The action's result, or a rejection if the id is unknown or it threw.
+     */
+    run<K extends EngineActionId>(id: K, ...args: EngineActionsRegistry[K] extends (...args: infer A) => any ? A : unknown[]): Promise<EngineActionsRegistry[K] extends (...args: any[]) => infer R ? Awaited<R> : unknown>;
+    run<R = unknown>(id: string, ...args: unknown[]): Promise<R>;
+    /** Whether an action with this id is registered (host or engine default). */
+    has(id: string): boolean;
+    /**
+     * Remove a host action, or revert an overridden engine default to its built-in.
+     *
+     * If you override an engine default (such as `select` or `undo`), unregistering the id restores
+     * the default rather than leaving it unhandled. A custom id you registered yourself is removed
+     * entirely. Returns `false` only when the id is unknown.
+     */
+    unregister(id: string): boolean;
+    /** List registered actions, optionally filtered by a `*` glob matcher on the id. */
+    list(options?: {
+        matcher?: string;
+    }): EngineActionInfo[];
+
+}
+
+/**
+ * @public Hook for hosts to add strongly-typed action ids. Augment via
+ * `declare module '@cesdk/engine'` to get autocomplete on register/run while
+ * still allowing custom string ids.
+ */
+export declare interface EngineActionsRegistry {
+}
+
+/** @public A generic, untyped action function for custom ids. */
+export declare type EngineCustomActionFunction = (...args: any[]) => unknown;
+
 /**
  * Represents an engine plugin.
  *
@@ -9882,6 +9979,7 @@ export declare interface Settings {
 
 
 
+
 
 
 }

package/index.d.ts

@@ -6684,6 +6684,12 @@ declare class CreativeEngine {
     event: EventAPI;
     scene: SceneAPI;
     variable: VariableAPI;
+    /**
+     * Register, run, and discover named, overridable actions. On headless Node the registry
+     * starts with only the engine-default `ly.img.*` actions (no host UI), but the API is
+     * identical to the browser engine.
+     */
+    actions: EngineActions;
     version: string;
 
     /**
@@ -8099,6 +8105,97 @@ export declare type EffectTypeLonghand = `//ly.img.ubq/effect/${EffectTypeShorth
 /** @public */
 export declare type EffectTypeShorthand = (typeof EFFECT_TYPES)[number];
 
+/** @public Known action ids from {@link EngineActionsRegistry}. */
+export declare type EngineActionId = keyof EngineActionsRegistry & string;
+
+/** @public Info about a registered action, from {@link EngineActions.list}. */
+export declare interface EngineActionInfo {
+    /** The action id, e.g. `nudge`. */
+    id: string;
+    /** Whether the action currently says it can run. */
+    enabled: boolean;
+    /** Optional JSON description of the arguments it accepts. */
+    argSchema: string | null;
+}
+
+/**
+ * @public Named, overridable actions for one engine. Actions are either JS
+ * closures you register or engine defaults (e.g. undo/redo), and
+ * either kind can override the other by reusing the id.
+ *
+ * JS-registered actions run directly in JS, so on the web you get full fidelity:
+ * {@link get} hands back the raw function and {@link run} passes args/results by
+ * reference (non-serializable payloads like File/Blob work). The engine also keeps
+ * a JSON trampoline per action so defaults run natively and host actions stay
+ * reachable across the FFI — that path is JSON-only and async. Engine defaults you
+ * have not overridden are reachable only via {@link run}; {@link get} returns undefined.
+ *
+ * @remarks Main-thread only. {@link get} is web-only; use run/has/list cross-platform.
+ */
+export declare class EngineActions {
+    #private;
+
+    /**
+     * Register an action, replacing any existing one with the same id.
+     *
+     * @param id - The action id (e.g. `undo`). Reusing an engine default's id overrides it.
+     * @param fn - The action body (sync or async). On the web it runs directly with
+     *   any JS values. Across the FFI args/results are JSON, so only serializable
+     *   payloads work there.
+     */
+    register<K extends EngineActionId>(id: K, fn: EngineActionsRegistry[K] extends (...args: any[]) => any ? EngineActionsRegistry[K] : EngineCustomActionFunction): void;
+    register(id: string, fn: EngineCustomActionFunction): void;
+    /**
+     * Get the raw registered function for an id so you can call it synchronously.
+     *
+     * Returns the exact function you registered. Returns `undefined` for unknown ids
+     * and engine-default native actions (which have no JS function) — use {@link run}
+     * for those.
+     *
+     * @remarks Web-only.
+     */
+    get<K extends EngineActionId>(id: K): EngineActionsRegistry[K] | undefined;
+    get(id: string): EngineCustomActionFunction | undefined;
+    /**
+     * Run an action by id and return its result as a Promise.
+     *
+     * JS-registered actions are called directly (args/result by reference). Engine
+     * defaults go across the FFI (JSON args/result).
+     *
+     * @param id - The action id.
+     * @param args - Arguments forwarded to the action.
+     * @returns The action's result, or a rejection if the id is unknown or it threw.
+     */
+    run<K extends EngineActionId>(id: K, ...args: EngineActionsRegistry[K] extends (...args: infer A) => any ? A : unknown[]): Promise<EngineActionsRegistry[K] extends (...args: any[]) => infer R ? Awaited<R> : unknown>;
+    run<R = unknown>(id: string, ...args: unknown[]): Promise<R>;
+    /** Whether an action with this id is registered (host or engine default). */
+    has(id: string): boolean;
+    /**
+     * Remove a host action, or revert an overridden engine default to its built-in.
+     *
+     * If you override an engine default (such as `select` or `undo`), unregistering the id restores
+     * the default rather than leaving it unhandled. A custom id you registered yourself is removed
+     * entirely. Returns `false` only when the id is unknown.
+     */
+    unregister(id: string): boolean;
+    /** List registered actions, optionally filtered by a `*` glob matcher on the id. */
+    list(options?: {
+        matcher?: string;
+    }): EngineActionInfo[];
+
+}
+
+/**
+ * @public Hook for hosts to add strongly-typed action ids. Augment via
+ * `declare module '@cesdk/engine'` to get autocomplete on register/run while
+ * still allowing custom string ids.
+ */
+export declare interface EngineActionsRegistry {
+}
+
+/** @public A generic, untyped action function for custom ids. */
+export declare type EngineCustomActionFunction = (...args: any[]) => unknown;
+
 /**
  * Represents an engine plugin.
  *
@@ -9882,6 +9979,7 @@ export declare interface Settings {
 
 
 
+
 
 
 }