@cesdk/cesdk-js 1.77.0-rc.3 → 1.77.0-rc.4

package/index.d.ts

@@ -3850,6 +3850,20 @@ export { EngineErrorArg }
 
 export { EngineErrorCode }
 
+/**
+ * Customer-facing copy resolved from a thrown engine error.
+ *
+ * `message` is the short headline (only set for a structured {@link EngineError});
+ * `description` is the longer body. Either may be absent — callers fall back to
+ * their own contextual copy for whichever half is missing.
+ */
+export declare interface EngineErrorMessage {
+    /** Short headline. Set only for a {@link EngineError} with a catalog code. */
+    message?: string;
+    /** Longer body: the engine `hint` for catalog errors, else the raw message. */
+    description?: string;
+}
+
 export { EngineExportOptions }
 
 export { EnginePlugin }
@@ -4952,6 +4966,7 @@ export declare class InternationalizationAPI {
      *
      * @category Localization
      * @param key - A translation key string or an array of translation keys to try in order.
+     * @param options - Optional interpolation values for `{{placeholder}}` tokens in the resolved string.
      * @returns The translated string for the key in the current locale, or the key itself if no translation is found.
      *
      * @example
@@ -4964,9 +4979,42 @@ export declare class InternationalizationAPI {
      * const translation = cesdk.i18n.translate(['specific.save', 'common.save']);
      * // Tries 'specific.save' first, then 'common.save'
      * // Returns the first found translation or "common.save" if neither exists
+     *
+     * // With interpolation values
+     * const translation = cesdk.i18n.translate('error.fileTooLarge', { maxSize: '10MB' });
+     * ```
+     */
+    translate(key: string | string[], options?: Record<string, unknown>): string;
+    /**
+     * Resolves a thrown engine error into the customer-facing copy the editor's
+     * built-in error dialogs display.
+     *
+     * Use this in your own error handling—a custom `onError`, a toast, or a
+     * headless flow—to show the same localized text without reimplementing the
+     * lookup. For a {@link @cesdk/engine#EngineError} with a catalog
+     * `code` it returns your authored `error.<code>` / `error.<code>.description`
+     * override (registered via {@link setTranslations}), falling back to the
+     * engine's English message and hint when no copy is authored—so the result is
+     * never blank or a raw code. Plain `Error`s return only a `description` (their
+     * message); branch on the structured `code` rather than the message string for
+     * stable handling.
+     *
+     * @category Localization
+     * @param error - The thrown error, typically caught from an engine operation.
+     * @returns The resolved `{ message, description }` copy, or `undefined` when
+     *   there is nothing to show.
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await cesdk.engine.scene.loadFromURL(sceneUrl);
+     * } catch (error) {
+     *   const copy = cesdk.i18n.localizedEngineErrorMessage(error);
+     *   showToast(copy?.message ?? copy?.description ?? 'Something went wrong.');
+     * }
      * ```
      */
-    translate(key: string | string[]): string;
+    localizedEngineErrorMessage(error: unknown): EngineErrorMessage | undefined;
 }
 
 /**
@@ -5077,9 +5125,9 @@ export declare type KeyboardShortcutContext = {
  * `cesdk.shortcuts` — the editor-facing keyboard shortcut API.
  *
  * A thin wrapper over the engine's `engine.shortcuts` registry that translates
- * the editor-facing KeyboardShortcut (whose `when`/`run` receive
- * `{ cesdk }`) to/from the engine Shortcut (whose callbacks receive
- * `{ engine }`). The `cesdk` instance is closed over here so the engine layer
+ * the editor-facing KeyboardShortcut (whose `when`/`run` receive a context with
+ * `cesdk`) to/from the engine Shortcut (whose callbacks receive a context with
+ * `engine`). The `cesdk` instance is closed over here so the engine layer
  * never needs to know about it.
  *
  * @public
@@ -5101,8 +5149,8 @@ export declare class KeyboardShortcutsAPI {
     set(shortcut: KeyboardShortcut | KeyboardShortcut[]): () => void;
     /**
      * List the keyboard shortcuts matching `options` (`keys` AND `scopes`,
-     * glob-matched). Both fields are required and must be non-empty;
-     * `{ keys: '*', scopes: '*' }` lists everything. Throws on an empty field.
+     * glob-matched). Both fields are required and must be non-empty; using `'*'`
+     * for both `keys` and `scopes` lists everything. Throws on an empty field.
      * @public
      */
     list(options: {
@@ -5120,8 +5168,9 @@ export declare class KeyboardShortcutsAPI {
     }): KeyboardShortcut | undefined;
     /**
      * Remove every keyboard shortcut matching `options` (`keys` AND `scopes`).
-     * Both fields are required and must be non-empty; use `'*'` to match all
-     * (e.g. `{ keys: 'Mod+s', scopes: '*' }`). Throws on an empty field.
+     * Both fields are required and must be non-empty; use `'*'` to match all —
+     * for example, `keys: 'Mod+s'` with `scopes: '*'` removes that chord from
+     * every scope. Throws on an empty field.
      * @public
      */
     remove(options: {