Skip to content

Commit fc6d88d

Browse files
Merge pull request #251 from SenteraLLC/feature/destroy
feature/destroy
2 parents 7591f0e + 901f2ba commit fc6d88d

11 files changed

Lines changed: 566 additions & 16 deletions

File tree

‎.github/tasks.md‎

Lines changed: 0 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,3 @@
11
## Tasks
22

3-
### Bitmask segmentation annotation mode
4-
Per-annotation binary masks, COCO-style RLE serialization, brush + erase interaction.
5-
6-
- [x] Phase 1: Data model + RLE utils + tests (`src/mask_utils.ts`, `ULabelSpatialType`, `SPATIAL_TYPE_SET`)
7-
- [x] Phase 2: Bitmask rendering layer (`draw_bitmask`, dispatch, redraw/clear)
8-
- [x] Phase 3: Brush/erase paints pixels (begin/continue/finish for bitmask)
9-
- [x] Phase 4: Undo/redo patch diffs for brush strokes (single-stroke `bitmask_stroke` action)
10-
- [x] Phase 5: Toolbox + mode registration (mode button, brush enable/disable, keybinds)
11-
- [ ] Phase 6: Export/import round-trip + tests + demo page
123

‎CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,14 @@ All notable changes to this project will be documented here.
44

55
## [unreleased]
66

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+
715

816
## [0.25.1] - Aug 10th, 2026
917
- The `ConfidenceSlider` toolbox item now also filters `bitmask` annotations

‎api_spec.md‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@ ulabel.init(() => {/* behavior on ready */})
3232

3333
`ULabel` is the only name that `ulabel.js` will add to the global namespace.
3434

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+
3537
The constructor is used to specify the configuration for an "annotation session". It has the following interface
3638

3739
```javascript
@@ -79,7 +81,8 @@ class ULabel({
7981
annotation_size_minus_keybind: string,
8082
annotation_vanish_keybind: string,
8183
fly_to_max_zoom: number,
82-
n_annos_per_canvas: number
84+
n_annos_per_canvas: number,
85+
auto_destroy_on_detach: boolean
8386
})
8487
```
8588

@@ -615,6 +618,11 @@ If `true`, the user can click and drag to contiuously place points for polyline
615618
### `allow_annotations_outside_image`
616619
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`.
617620
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+
618626
619627
## Display Utility Functions
620628
@@ -653,6 +661,23 @@ Display utilities are provided for a constructed `ULabel` object.
653661
*() => void* -- Removes persistent event listeners from the document and window. Listeners attached directly to html elements are not explicitly removed.
654662
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.
655663
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`),
671+
- action stream and redo stack (which retain per-stroke `before_rle` / `after_rle` payloads),
672+
- toolbox item back-references to the instance,
673+
- 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+
656681
### `fly_to_next_annotation(increment)`
657682
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).
658683

‎index.d.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -300,6 +300,7 @@ export type ULabelConstructorArgs = {
300300
initial_line_size?: number;
301301
instructions_url?: string;
302302
toolbox_order?: AllowedToolboxItem[];
303+
auto_destroy_on_detach?: boolean;
303304
/** @deprecated Use top-level properties instead. */
304305
config_data?: object;
305306
};
@@ -439,6 +440,16 @@ export class ULabel {
439440
// Listeners
440441
public remove_listeners(): void;
441442

443+
// Full teardown: releases bitmask caches, action streams, toolbox refs, and container DOM.
444+
public destroy(): void;
445+
// True after destroy() has run; subsequent destroy() calls are no-ops.
446+
is_destroyed: boolean;
447+
// The container HTMLElement this instance owns, captured at init. Used by destroy() and
448+
// the auto-teardown observer to avoid mistaking a same-id replacement for our container.
449+
_owned_container: HTMLElement | null;
450+
// Install the auto-teardown MutationObserver; called by init and idempotent.
451+
_install_auto_destroy_observer(): void;
452+
442453
// Static functions
443454
static version(): string;
444455
static get_time(): string;

‎package-lock.json‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "ulabel",
33
"description": "An image annotation tool.",
4-
"version": "0.25.1",
4+
"version": "0.26.0",
55
"main": "dist/ulabel.min.js",
66
"module": "dist/ulabel.min.js",
77
"types": "dist/index.d.ts",

‎src/configuration.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -276,6 +276,8 @@ export class Configuration {
276276

277277
public allow_annotations_outside_image: boolean = true;
278278

279+
public auto_destroy_on_detach: boolean = true;
280+
279281
constructor(...kwargs: { [key: string]: unknown }[]) {
280282
this.modify_config(...kwargs);
281283
}

0 commit comments

Comments
 (0)