You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit fc6d88d
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: CHANGELOG.md
+8Lines changed: 8 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,6 +4,14 @@ All notable changes to this project will be documented here.
4
4
5
5
## [unreleased]
6
6
7
+
## [0.26.0] - Aug 11th, 2026
8
+
-**Memory leak fix on teardown.** Bitmask annotations attach a decoded pixel `Uint8Array` (`_mask`) and a tinted stencil canvas (`_mask_render`) to each annotation object. These persisted after `remove_listeners()`, and consumers that rebuild ULabel per navigation could accumulate multi-GB retained heap. Changes:
9
+
- New `destroy()` method on `ULabel`. Idempotent; releases per-annotation bitmask caches, empties action/undo streams, breaks toolbox back-references, clears the resize-observer array, and wipes the container DOM. Callers should prefer `destroy()` over `remove_listeners()` going forward.
10
+
-`destroy_annotation_context()` now also drops `_mask` / `_mask_render` / `_bitmask_box_hint` on the destroyed annotation, so `set_annotations()` also frees mask memory when it recycles contexts.
11
+
- New `auto_destroy_on_detach` config option (default `true`). When enabled, ULabel installs a `MutationObserver` on the container's root and calls `destroy()` automatically after the container leaves the DOM.
12
+
-`set_annotations()`, `get_annotations()`, and `redraw_all_annotations()` now short-circuit with a warning if called after `destroy()`.
13
+
- Fixed a latent typo in `set_annotations()` that wrote to a non-existent `undo_stack` property instead of clearing the real `undone_stack`.
14
+
7
15
8
16
## [0.25.1] - Aug 10th, 2026
9
17
- The `ConfidenceSlider` toolbox item now also filters `bitmask` annotations
`ULabel` is the only name that `ulabel.js` will add to the global namespace.
34
34
35
+
> 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.
36
+
35
37
The constructor is used to specify the configuration for an "annotation session". It has the following interface
36
38
37
39
```javascript
@@ -79,7 +81,8 @@ class ULabel({
79
81
annotation_size_minus_keybind: string,
80
82
annotation_vanish_keybind: string,
81
83
fly_to_max_zoom: number,
82
-
n_annos_per_canvas: number
84
+
n_annos_per_canvas: number,
85
+
auto_destroy_on_detach: boolean
83
86
})
84
87
```
85
88
@@ -615,6 +618,11 @@ If `true`, the user can click and drag to contiuously place points for polyline
615
618
### `allow_annotations_outside_image`
616
619
When `false`, new annotations will be limited to points within the image, and attempts to move annotations outside the image will bounce back to inside the image. Default is `true`.
617
620
621
+
### `auto_destroy_on_detach`
622
+
When `true` (the default), ULabel installs a `MutationObserver` on the container's root and calls [`destroy()`](#destroy) automatically after the container is removed from the DOM. The observer holds the ULabel instance through a `WeakRef` (so it cannot pin the instance in memory on its own) and defers the teardown decision by one animation frame so brief detach/reattach cycles (portals, jQuery `.detach()`, layout reparenting) do not trigger a false-positive teardown. Set to `false` to opt out and manage teardown manually via [`destroy()`](#destroy).
623
+
624
+
> **Same-id replacement caveat.** With the default `true`, the one-frame grace period means a caller who removes the old container and mounts a new `<div>` with the same `container_id` *within the same animation frame* can briefly have two `ULabel` instances attached to `document`; when the old instance's teardown runs it will remove `.ulabel`-namespaced document/window handlers belonging to the new instance too. If your SPA does synchronous same-id replacement, set `auto_destroy_on_detach:false` and call `oldUlabel.destroy()` yourself *before* mounting the replacement — `destroy()` is synchronous, so this ordering is race-free.
625
+
618
626
619
627
## Display Utility Functions
620
628
@@ -653,6 +661,23 @@ Display utilities are provided for a constructed `ULabel` object.
653
661
*() => void* -- Removes persistent event listeners from the document and window. Listeners attached directly to html elements are not explicitly removed.
654
662
Note that ULabel will not function properly after this method is called. Designed for use in single-page applications before navigating away from the annotation page.
655
663
664
+
> Prefer [`destroy()`](#destroy) for new code — it also releases the heavy per-annotation bitmask caches and the container DOM.
665
+
666
+
### `destroy()`
667
+
668
+
*() => void* -- Fully tears down this ULabel instance. Idempotent (subsequent calls are no-ops). Releases:
669
+
670
+
- per-bitmask runtime state (`_mask``Uint8Array`, `_mask_render` tinted stencil canvas, `_bitmask_box_hint`),
- resize observers and (if [`auto_destroy_on_detach`](#auto_destroy_on_detach) installed one) the auto-teardown `MutationObserver`,
674
+
- pending toast/interaction timers,
675
+
- all DOM under the configured container.
676
+
677
+
After calling `destroy()` the instance MUST NOT be used again. `set_annotations()`, `get_annotations()`, and `redraw_all_annotations()` short-circuit with a warning if called on a destroyed instance.
678
+
679
+
With [`auto_destroy_on_detach`](#auto_destroy_on_detach) enabled (the default), `destroy()` is called automatically after the container is removed from the DOM. Callers that opt out of the auto path should call `destroy()` explicitly during their unmount / teardown.
680
+
656
681
### `fly_to_next_annotation(increment)`
657
682
Sets the zoom to focus on a non-deprecated, spatial annotation in the active subtask's ordering that is an `<increment>` number away from the previously focused annotation, if any. Returns `true` on success and `false` on failure (eg, no valid annotations exist, or an annotation is currently actively being edited).
0 commit comments