Return ulabel_init

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to this project will be documented here.
 
+## [0.30.0] - Oct 20th, 2026
+#### Changed
+- `init()` now returns the `ulabel_init`; typed `Promise<void>`
+
 ## [0.29.1] - Oct 12th, 2026
 #### Fixed
 - `set_annotations()` / `set_annotations_batch()` could paint a frame with no annotations on heavy images. The outgoing annotations now stay on screen until the new ones are drawn.

api_spec.md

@@ -35,6 +35,14 @@ Note that in order to begin the session, you must thereafter call
 ulabel.init(() => {/* behavior on ready */})
 ```
 
+`init()` returns a `Promise<void>` that:
+
+- Resolves when initialization finishes (after the callback)
+- Resolves early without calling the callback if [`destroy()`](#destroy)
+  runs mid-init; check `ulabel.is_destroyed` after awaiting
+- Rejects if initialization fails (e.g. the image fails to decode)
+- Rejects if the callback fails
+
 `ULabel` is the only name that `ulabel.js` will add to the global namespace.
 
 > ULabel is designed for **a single instance per page**. Toolbox handlers, id dialogs, and global keybinds bind to shared DOM ids and delegated selectors on `document`, so mounting more than one `ULabel` simultaneously is not supported.

index.d.ts

@@ -507,7 +507,7 @@ export class ULabel {
      * @link https://github.com/SenteraLLC/ulabel/blob/main/api_spec.md#display-utility-functions
      */
     public version(): string;
-    public init(callback: () => void): void;
+    public init(callback: () => void): Promise<void>;
     public after_init(): void;
     public show_initial_crop(): void;
     public show_whole_image(): void;

package.json

@@ -1,7 +1,7 @@
 {
   "name": "ulabel",
   "description": "An image annotation tool.",
-  "version": "0.29.1",
+  "version": "0.30.0",
   "main": "dist/ulabel.min.js",
   "module": "dist/ulabel.min.js",
   "types": "dist/index.d.ts",

src/index.js

@@ -844,8 +844,14 @@ export class ULabel {
         this._owned_container = null;
     }
 
+    /**
+     * Initialize the session, then call the user callback.
+     *
+     * @param {() => void} callback User-provided callback to run after initialization.
+     * @returns {Promise<void>} Resolves when initialization finishes; rejects if it fails.
+     */
     init(callback) {
-        ulabel_init(this, callback);
+        return ulabel_init(this, callback);
     }
 
     /**

src/version.js

@@ -1 +1 @@
-export const ULABEL_VERSION = "0.29.1";
+export const ULABEL_VERSION = "0.30.0";