feat(api,web): delta label protocol — labelling is now O(edit), not O(cloud)

Every label edit (assign, undo, redo, group assigns, apply-suggested) used
to ship the full label array back and recompute + re-upload colours for
every point — ~160 MB of work per click on a 10M-point cloud. Now:

- InteractionController's label-editing methods return the touched indices.
- AnnotationService.state(touched=...) responds with labels_delta
{indices, values} instead of the full labels/grouping arrays.
- The client patches its cached labels, recolours only the touched points
(colors.js: makeLabelColorizer is the single per-point rule shared by the
full recompute and the delta path, so they cannot drift), re-evaluates
visibility only where it can change (touched + both selections), and
uploads just the coalesced dirty ranges (viewer.commitColors).
- Isolate mode falls back to the full recompute — its alpha is a function
of the whole selection, not of the edit.

tests/test_web_ui.py drives the real stack headless (worker octree, motion
cut, pick equivalence) and asserts the delta-patched buffers are
byte-identical to a from-scratch full-state re-render, with and without
the hide-labelled visibility mask, including across undo.

tests/test_api.py

@@ -62,9 +62,13 @@ def test_segment_then_assign_group(client):
     sel = client.post("/api/group/select", json={"group_id": gid}).json()
     assert decode_array(sel["selection"]).size == snap["segments"][0]["count"]
 
-    # Label that segment with class 4.
+    # Label that segment with class 4 — the response is a delta, not full labels.
     after = client.post("/api/group/assign", json={"group_id": gid, "class_id": 4}).json()
-    labels = decode_array(after["labels"])
+    delta = after["labels_delta"]
+    assert decode_array(delta["indices"]).size == snap["segments"][0]["count"]
+    assert (decode_array(delta["values"]) == 4).all()
+    # The full state still reflects the write.
+    labels = decode_array(client.get("/api/state").json()["labels"])
     assert int((labels == 4).sum()) == snap["segments"][0]["count"]
 
 
@@ -88,8 +92,11 @@ def test_assign_visible_groups_endpoint(client):
     # Uncheck one segment, then assign class 3 to the visible (checked) ones.
     client.post("/api/group/visibility", json={"group_id": hide["id"], "visible": False})
     after = client.post("/api/groups/assign_visible", json={"class_id": 3}).json()
-    labels = decode_array(after["labels"])
+    delta = after["labels_delta"]
     # Exactly the visible segment's points became class 3; the hidden one did not.
+    assert decode_array(delta["indices"]).size == sum(s["count"] for s in segs if s["id"] != hide["id"])
+    assert (decode_array(delta["values"]) == 3).all()
+    labels = decode_array(client.get("/api/state").json()["labels"])
     assert int((labels == 3).sum()) == sum(s["count"] for s in segs if s["id"] != hide["id"])
 
 
@@ -126,9 +133,12 @@ def test_pick_assign_undo(client):
     client.post("/api/active_class", json={"class_id": 2})
     client.post("/api/pick", json={"index": 5})
     after = client.post("/api/assign", json={}).json()
-    assert decode_array(after["labels"])[5] == 2
+    assert decode_array(after["labels_delta"]["indices"]).tolist() == [5]
+    assert decode_array(after["labels_delta"]["values"]).tolist() == [2]
     back = client.post("/api/undo").json()
-    assert decode_array(back["labels"])[5] == 0
+    assert decode_array(back["labels_delta"]["indices"]).tolist() == [5]
+    assert decode_array(back["labels_delta"]["values"]).tolist() == [0]
+    assert decode_array(client.get("/api/state").json()["labels"])[5] == 0
 
 
 def test_browse_lists_dir_and_flags_openable(client, tmp_path):

tests/test_controller.py

@@ -127,8 +127,8 @@ def test_assign_group_labels_the_segment(two_clusters, schema):
     viewer = FakeViewer()
     ctl = InteractionController(session, viewer)
     ctl.set_active_class(1)
-    n = ctl.assign_group(0)
-    assert n == 50
+    touched = ctl.assign_group(0)
+    assert touched.size == 50
     assert (session.cloud.labels[:50] == 1).all()
     assert (session.cloud.labels[50:] == 0).all()
     assert viewer.recolored  # labelled points are repainted in any view
@@ -138,23 +138,23 @@ def test_apply_suggested_single_and_all(two_clusters, schema):
     session = _grouped_session(two_clusters, schema)
     ctl = InteractionController(session, FakeViewer())
     # Only group 1 carries a suggestion (-> class 2).
-    n = ctl.apply_suggested(1)
-    assert n == 50
+    touched = ctl.apply_suggested(1)
+    assert touched.size == 50
     assert (session.cloud.labels[50:] == 2).all()
     # Group 0 has no suggestion -> no-op.
-    assert ctl.apply_suggested(0) == 0
+    assert ctl.apply_suggested(0).size == 0
     # "All suggested" applies every group that has one.
     session2 = _grouped_session(two_clusters, schema)
     ctl2 = InteractionController(session2, FakeViewer())
-    assert ctl2.apply_suggested(None) == 50
+    assert ctl2.apply_suggested(None).size == 50
 
 
 def test_group_ops_noop_without_active_grouping(two_clusters, schema):
     two_clusters.ensure_labels(schema.unlabeled_id)
     session = Session(two_clusters, schema)  # no grouping
     ctl = InteractionController(session, FakeViewer())
-    assert ctl.assign_group(0) == 0
-    assert ctl.apply_suggested() == 0
+    assert ctl.assign_group(0).size == 0
+    assert ctl.apply_suggested().size == 0
 
 
 def test_group_visibility_commands(two_clusters, schema):
@@ -187,9 +187,9 @@ def test_assign_visible_groups_labels_only_checked(two_clusters, schema):
     # Uncheck (hide) group 0, then assign -> only the visible group 1 is labelled.
     ctl.set_group_visibility(0, False)
     ctl.set_active_class(2)
-    n = ctl.assign_visible_groups()
+    touched = ctl.assign_visible_groups()
     labels = session.cloud.labels
-    assert n == 50
+    assert touched.size == 50
     assert (labels[:50] == schema.unlabeled_id).all()  # hidden group untouched
     assert (labels[50:] == 2).all()  # checked group labelled
 
@@ -204,7 +204,7 @@ def test_clear_grouping_discards_segmentation_keeps_labels(two_clusters, schema)
     ctl.set_display_mode("grouping")
     # Label a segment first — its labels must survive the grouping being dropped.
     labelled = ctl.assign_group(0, 1)
-    assert labelled == 50
+    assert labelled.size == 50
 
     ctl.clear_grouping()
     assert session.active_grouping is None

tests/test_web_ui.py

@@ -0,0 +1,258 @@
+"""End-to-end checks of the web viewer's octree LOD/picking and delta recolour.
+
+Drives the real stack — ``toaster-web`` served from THIS checkout, headless
+Chromium via Playwright — against a synthetic cloud big enough to build the
+octree and trip the motion LOD (> 1M points). Skips cleanly when Playwright
+or its browser is unavailable.
+
+Invariants covered:
+- the worker-built octree is a permutation of the cloud with well-formed,
+  disjoint node slices;
+- camera motion renders the octree cut (a strict subset), idle refines back
+  to the full cloud, and the rAF loop parks afterwards (the QtWebEngine
+  leak guard);
+- octree pick/pickBox return exactly what the brute-force scans return;
+- after delta-applied label edits (assign, undo), the client's colour/alpha
+  buffers are indistinguishable from a from-scratch full-state re-render.
+"""
+
+from __future__ import annotations
+
+import os
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+pytest.importorskip("playwright.sync_api")
+from playwright.sync_api import sync_playwright  # noqa: E402
+
+REPO = Path(__file__).resolve().parent.parent
+N_POINTS = 1_200_000  # > LOD_BUDGET (1M) so the motion cut engages
+
+
+def _free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+@pytest.fixture(scope="module")
+def server(tmp_path_factory):
+    """toaster-web on a random port, serving a 1.2M-point synthetic terrain."""
+    cloud = tmp_path_factory.mktemp("cloud") / "big.bin"
+    rng = np.random.default_rng(7)
+    xy = rng.uniform(-50, 50, (N_POINTS, 2)).astype(np.float32)
+    z = (np.sin(xy[:, 0] * 0.2) * np.cos(xy[:, 1] * 0.15) + rng.normal(0, 0.1, N_POINTS)).astype(
+        np.float32
+    )
+    i = rng.uniform(0, 1, N_POINTS).astype(np.float32)
+    np.column_stack([xy, z, i]).astype(np.float32).tofile(cloud)
+
+    port = _free_port()
+    env = os.environ | {"PYTHONPATH": str(REPO)}  # serve THIS checkout, not the installed copy
+    proc = subprocess.Popen(
+        [sys.executable, "-m", "toaster.api.server", str(cloud), "--port", str(port)],
+        env=env,
+        cwd=REPO,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.PIPE,
+    )
+    import urllib.request
+
+    deadline = time.time() + 30
+    while True:
+        try:
+            urllib.request.urlopen(f"http://127.0.0.1:{port}/api/meta", timeout=1)
+            break
+        except Exception:
+            if proc.poll() is not None:
+                pytest.skip(f"server died: {proc.stderr.read().decode()[-500:]}")
+            if time.time() > deadline:
+                proc.kill()
+                pytest.skip("server did not come up in 30s")
+            time.sleep(0.3)
+    yield f"http://127.0.0.1:{port}"
+    proc.terminate()
+    proc.wait(timeout=10)
+
+
+@pytest.fixture(scope="module")
+def page(server):
+    """One loaded page (cloud + octree ready) shared by the module's tests."""
+    with sync_playwright() as p:
+        try:
+            browser = p.chromium.launch()
+        except Exception as exc:  # no browser installed
+            pytest.skip(f"chromium unavailable: {exc}")
+        page = browser.new_page(viewport={"width": 1280, "height": 800})
+        errors: list[str] = []
+        page.on("pageerror", lambda e: errors.append(f"pageerror: {e}"))
+        page.on(
+            "console",
+            lambda m: errors.append(f"console: {m.text}") if m.type == "error" else None,
+        )
+        page.goto(server)
+        page.wait_for_function(
+            f"window.__toaster && window.__toaster.viewer.geom && "
+            f"window.__toaster.viewer.geom.getAttribute('position').count === {N_POINTS}",
+            timeout=90000,
+        )
+        page.wait_for_function("window.__toaster.viewer._octree !== null", timeout=90000)
+        page._errors = errors
+        yield page
+        assert not errors, f"console/page errors: {errors}"
+        browser.close()
+
+
+def test_octree_is_a_permutation_with_wellformed_slices(page):
+    ok = page.evaluate(
+        f"""(() => {{
+          const o = window.__toaster.viewer._octree.data;
+          if (o.order.length !== {N_POINTS}) return "bad order length";
+          const seen = new Uint8Array({N_POINTS});
+          for (let k = 0; k < o.order.length; k++) {{
+            if (seen[o.order[k]]) return "duplicate index";
+            seen[o.order[k]] = 1;
+          }}
+          for (let i = 0; i < seen.length; i++) if (!seen[i]) return "missing index";
+          for (let ni = 0; ni < o.start.length; ni++) {{
+            if (o.start[ni] + o.count[ni] > o.order.length) return "slice out of bounds";
+            for (let c = 0; c < 8; c++) {{
+              const ch = o.children[ni * 8 + c];
+              if (ch >= 0 && o.start[ch] < o.start[ni] + o.count[ni])
+                return "child overlaps parent sample";
+            }}
+          }}
+          return "ok";
+        }})()"""
+    )
+    assert ok == "ok"
+
+
+def test_motion_draws_octree_cut_then_idle_refines_full(page):
+    # A held fly key keeps the view "in motion" for as long as we need to
+    # observe it (a drag's 150 ms settle window is shorter than one headless
+    # software-GL frame, so the refine would race the assertion).
+    page.click("canvas", position={"x": 10, "y": 10})
+    page.keyboard.down("w")
+    time.sleep(0.4)
+    during = page.evaluate(
+        """(() => {
+          const v = window.__toaster.viewer;
+          return { cut: v.geom.index === v._drawAttr, n: v.geom.drawRange.count };
+        })()"""
+    )
+    page.keyboard.up("w")
+    assert during["cut"], "motion frames must render the octree cut"
+    assert 0 < during["n"] < N_POINTS, "the cut must be a strict subset"
+
+    time.sleep(1.5)  # settle + slow software-GL frames
+    after = page.evaluate(
+        "(() => { const v = window.__toaster.viewer;"
+        " return v.geom.index === null && !v._lodOn; })()"
+    )
+    assert after, "idle must refine back to the full cloud"
+
+    # The rAF loop must park at idle (the QtWebEngine leak guard).
+    for _ in range(4):
+        assert page.evaluate("window.__toaster.viewer._rafPending") is not True
+        time.sleep(0.4)
+
+
+def test_octree_picking_matches_brute_force(page):
+    out = page.evaluate(
+        """(() => {
+          const v = window.__toaster.viewer;
+          const pick1 = v.pick(640, 400);
+          const box1 = v.pickBox(610, 370, 670, 430);
+          const oct = v._octree;
+          v._octree = null; // brute-force path
+          const pick2 = v.pick(640, 400);
+          const box2 = v.pickBox(610, 370, 670, 430);
+          v._octree = oct;
+          box1.sort((a, b) => a - b);
+          box2.sort((a, b) => a - b);
+          return {
+            pickSame: pick1 === pick2,
+            picked: pick1,
+            boxSame: box1.length === box2.length && box1.every((x, i) => x === box2[i]),
+            boxN: box1.length,
+          };
+        })()"""
+    )
+    assert out["pickSame"], "octree pick must match the exact scan"
+    assert out["picked"] >= 0
+    assert out["boxSame"], "octree pickBox must match the exact scan"
+    assert out["boxN"] > 0
+
+
+def test_delta_recolor_matches_full_rerender(page):
+    # Box-select a screen region, label it, and compare the delta-patched
+    # colour/alpha buffers against a from-scratch full-state re-render —
+    # byte-identical or the delta path has drifted from the reference rules.
+    # Drive the real UI: box mode, rubber-band drag, double-click to label.
+    page.click("button[data-mode-pick=box]")
+    page.mouse.move(560, 320)
+    page.mouse.down()
+    page.mouse.move(720, 480, steps=5)
+    page.mouse.up()
+    page.wait_for_function(
+        "window.__toaster.debug.getState().selection.length > 0", timeout=15000
+    )
+    page.mouse.dblclick(640, 440)  # viewport coords, inside the drawn box — delta path
+    page.wait_for_function(
+        "window.__toaster.debug.getState().selection.length === 0", timeout=15000
+    )
+
+    def buffers_equal_after_full_refresh() -> dict:
+        return page.evaluate(
+            """(async () => {
+              const { viewer, debug } = window.__toaster;
+              const live = viewer.colorArrays();
+              const colors = live.colors.slice();
+              const alpha = live.alpha.slice();
+              await debug.refresh(); // from-scratch reference render
+              const ref = viewer.colorArrays();
+              let colorDiff = 0, alphaDiff = 0;
+              for (let i = 0; i < colors.length; i++) if (colors[i] !== ref.colors[i]) colorDiff++;
+              for (let i = 0; i < alpha.length; i++) if (alpha[i] !== ref.alpha[i]) alphaDiff++;
+              const labeled = debug.getState().labels.reduce((a, v) => a + (v !== 0 ? 1 : 0), 0);
+              return { colorDiff, alphaDiff, labeled };
+            })()"""
+        )
+
+    out = buffers_equal_after_full_refresh()
+    assert out["labeled"] > 0, "the double-click must have labelled the box selection"
+    assert out["colorDiff"] == 0, f"{out['colorDiff']} colour slots diverged from the reference"
+    assert out["alphaDiff"] == 0, f"{out['alphaDiff']} alpha slots diverged from the reference"
+
+    # Same equivalence with the visibility mask active (hide-labelled points):
+    # the delta must now patch alphas too, and keep the hidden-count pill exact.
+    page.check("#hide-labeled")
+    page.mouse.move(400, 250)
+    page.mouse.down()
+    page.mouse.move(560, 400, steps=5)
+    page.mouse.up()
+    page.wait_for_function(
+        "window.__toaster.debug.getState().selection.length > 0", timeout=15000
+    )
+    page.mouse.dblclick(480, 330)  # viewport coords, inside the second box
+    page.wait_for_function(
+        "window.__toaster.debug.getState().selection.length === 0", timeout=15000
+    )
+    out = buffers_equal_after_full_refresh()
+    assert out["colorDiff"] == 0, "colours diverged with the visibility mask on"
+    assert out["alphaDiff"] == 0, "alphas diverged with the visibility mask on"
+
+    # Undo (a delta of the same edit, reversed) must also match the reference.
+    page.keyboard.press("Control+z")
+    time.sleep(0.5)
+    out = buffers_equal_after_full_refresh()
+    assert out["colorDiff"] == 0, "colours diverged after an undo delta"
+    assert out["alphaDiff"] == 0, "alphas diverged after an undo delta"
+    page.uncheck("#hide-labeled")

toaster/api/service.py

@@ -165,17 +165,33 @@ class AnnotationService:
         features = {k: encode_array(v) for k, v in ctl.session.cloud.features.items()}
         return {"xyz": encode_array(ctl.cloud_xyz()), "features": features}
 
-    def state(self) -> dict[str, Any]:
-        """Everything the client needs to (re)colour: snapshot + bulk arrays."""
+    def state(self, touched: np.ndarray | None = None) -> dict[str, Any]:
+        """Everything the client needs to (re)colour: snapshot + bulk arrays.
+
+        With ``touched`` (the indices a label edit wrote), the full label and
+        grouping arrays are replaced by ``labels_delta`` — just those indices
+        and their new values — so labelling stays O(edit), not O(cloud), on
+        the wire and in the client's recolour.
+        """
         ctl = self._ctl()
-        grouping = ctl.grouping_array()
-        return {
+        base = {
             "snapshot": asdict(ctl.snapshot()),
-            "labels": encode_array(ctl.label_array()),
-            "grouping": encode_array(grouping) if grouping is not None else None,
             # int32 so it maps to a JS Int32Array (int64 has no plain TypedArray).
             "selection": encode_array(ctl.selection_indices().astype(np.int32)),
         }
+        if touched is not None:
+            labels = ctl.label_array()
+            return base | {
+                "labels_delta": {
+                    "indices": encode_array(touched.astype(np.int32, copy=False)),
+                    "values": encode_array(labels[touched].astype(np.int32, copy=False)),
+                },
+            }
+        grouping = ctl.grouping_array()
+        return base | {
+            "labels": encode_array(ctl.label_array()),
+            "grouping": encode_array(grouping) if grouping is not None else None,
+        }
 
     # -- commands ---------------------------------------------------------
 
@@ -188,8 +204,7 @@ class AnnotationService:
         return self.state()
 
     def assign(self, class_id: int | None = None) -> dict[str, Any]:
-        self._ctl().assign(class_id)
-        return self.state()
+        return self.state(touched=self._ctl().assign(class_id))
 
     def set_active_class(self, class_id: int) -> dict[str, Any]:
         self._ctl().set_active_class(class_id)
@@ -200,12 +215,10 @@ class AnnotationService:
         return self.state()
 
     def undo(self) -> dict[str, Any]:
-        self._ctl().undo()
-        return self.state()
+        return self.state(touched=self._ctl().undo())
 
     def redo(self) -> dict[str, Any]:
-        self._ctl().redo()
-        return self.state()
+        return self.state(touched=self._ctl().redo())
 
     def clear_selection(self) -> dict[str, Any]:
         self._ctl().clear_selection()
@@ -242,16 +255,13 @@ class AnnotationService:
         return self.state()
 
     def assign_group(self, group_id: int, class_id: int | None = None) -> dict[str, Any]:
-        self._ctl().assign_group(group_id, class_id)
-        return self.state()
+        return self.state(touched=self._ctl().assign_group(group_id, class_id))
 
     def apply_suggested(self, group_id: int | None = None) -> dict[str, Any]:
-        self._ctl().apply_suggested(group_id)
-        return self.state()
+        return self.state(touched=self._ctl().apply_suggested(group_id))
 
     def assign_visible_groups(self, class_id: int | None = None) -> dict[str, Any]:
-        self._ctl().assign_visible_groups(class_id)
-        return self.state()
+        return self.state(touched=self._ctl().assign_visible_groups(class_id))
 
     def set_group_visibility(self, group_id: int, visible: bool) -> dict[str, Any]:
         self._ctl().set_group_visibility(group_id, visible)

toaster/interaction/controller.py

@@ -128,25 +128,34 @@ class InteractionController:
         self.session.active_class = class_id
         self._changed()
 
-    def assign(self, class_id: int | None = None) -> None:
-        """Write the active (or given) class to the current selection."""
+    def assign(self, class_id: int | None = None) -> np.ndarray:
+        """Write the active (or given) class to the current selection.
+
+        Returns the touched indices, so a remote front-end can patch labels and
+        colours in place instead of re-reading the full arrays.
+        """
         cid = self.session.active_class if class_id is None else class_id
         touched = self.session.annotation.assign(self.session.selection, cid)
         if touched.size:
             self._recolor_labels(touched)
         self.clear_selection()
+        return touched
 
-    def undo(self) -> None:
+    def undo(self) -> np.ndarray:
+        """Revert the last edit; returns the touched indices (empty if nothing)."""
         touched = self.session.annotation.undo()
         if touched is not None:
             self._recolor_labels(touched)
             self._changed()
+        return touched if touched is not None else np.empty(0, dtype=np.int64)
 
-    def redo(self) -> None:
+    def redo(self) -> np.ndarray:
+        """Re-apply the last undone edit; returns the touched indices (empty if nothing)."""
         touched = self.session.annotation.redo()
         if touched is not None:
             self._recolor_labels(touched)
             self._changed()
+        return touched if touched is not None else np.empty(0, dtype=np.int64)
 
     def _recolor_labels(self, indices: np.ndarray) -> None:
         # Only meaningful while showing labels; other modes recolour on switch.
@@ -190,27 +199,27 @@ class InteractionController:
             return
         self._apply_selection(Selection.from_group(grouping, group_id), modifiers)
 
-    def assign_group(self, group_id: int, class_id: int | None = None) -> int:
-        """Label a whole segment with the active (or given) class. Returns points labelled."""
+    def assign_group(self, group_id: int, class_id: int | None = None) -> np.ndarray:
+        """Label a whole segment with the active (or given) class. Returns touched indices."""
         grouping = self.session.active_grouping
         if grouping is None:
-            return 0
+            return np.empty(0, dtype=np.int64)
         cid = self.session.active_class if class_id is None else class_id
         touched = self.session.annotation.assign(Selection.from_group(grouping, group_id), cid)
         if touched.size:
             self._paint_labels(touched)
         self._changed()
-        return int(touched.size)
+        return touched
 
-    def assign_visible_groups(self, class_id: int | None = None) -> int:
+    def assign_visible_groups(self, class_id: int | None = None) -> np.ndarray:
         """Label every currently-visible (checked) segment with the active/given class.
 
         Hidden (unchecked, greyed) segments are skipped. The whole batch is one
-        undoable edit. Returns the number of points labelled.
+        undoable edit. Returns the touched indices.
         """
         grouping = self.session.active_grouping
         if grouping is None:
-            return 0
+            return np.empty(0, dtype=np.int64)
         cid = self.session.active_class if class_id is None else class_id
         sel = Selection.empty(self.session.cloud.n)
         for g in grouping.group_ids():
@@ -220,30 +229,30 @@ class InteractionController:
         if touched.size:
             self._paint_labels(touched)
         self._changed()
-        return int(touched.size)
+        return touched
 
-    def apply_suggested(self, group_id: int | None = None) -> int:
+    def apply_suggested(self, group_id: int | None = None) -> np.ndarray:
         """Accept model predictions: label group(s) with their ``suggested_labels``.
 
         With ``group_id`` set, only that segment; otherwise every segment that
-        carries a suggestion. Returns the number of points labelled.
+        carries a suggestion. Returns the touched indices across all of them.
         """
         grouping = self.session.active_grouping
         if grouping is None or not grouping.suggested_labels:
-            return 0
+            return np.empty(0, dtype=np.int64)
         if group_id is not None:
             suggestion = grouping.suggested_labels.get(group_id)
             items = [(group_id, suggestion)] if suggestion is not None else []
         else:
             items = list(grouping.suggested_labels.items())
-        total = 0
+        all_touched: list[np.ndarray] = []
         for gid, cid in items:
             touched = self.session.annotation.assign(Selection.from_group(grouping, gid), cid)
             if touched.size:
                 self._paint_labels(touched)
-                total += int(touched.size)
+                all_touched.append(touched)
         self._changed()
-        return total
+        return np.concatenate(all_touched) if all_touched else np.empty(0, dtype=np.int64)
 
     def _paint_labels(self, indices: np.ndarray) -> None:
         # Recolour assigned points to their class colour in *any* view, so a

toaster/web/js/app.js

@@ -2,12 +2,24 @@
 // wire interactions to the API, and re-render from each returned state.
 
 import { api, decodeArray } from "./api.js";
-import { computeColors } from "./colors.js";
+import { computeColors, makeLabelColorizer } from "./colors.js";
 import { Viewer } from "./viewer.js";
 
 const el = (id) => document.getElementById(id);
 const viewer = new Viewer(el("viewport"));
-window.__toaster = { viewer }; // debug / headless-test handle (module scope is unreachable from outside)
+// Debug / headless-test handle (module scope is unreachable from outside).
+// `refresh` re-pulls the full state and re-renders from scratch — the tests
+// use it as the reference the delta path must be indistinguishable from.
+window.__toaster = {
+  viewer,
+  debug: {
+    getState: () => state,
+    getCloud: () => cloud,
+    computeColors,
+    api,
+    refresh: async () => applyState(await api.state()),
+  },
+};
 
 let cloud = { xyz: null, features: {} };
 let state = null; // decoded { snapshot, labels, grouping, selection }
@@ -29,7 +41,7 @@ let voxel = { size: 0.5, showEmpty: false, map: null, centers: new Float32Array(
 const VOXEL_GRID_CAP = 30000; // max cubes to draw / cells to enumerate
 // The one point-visibility mask (class eyes ∧ hide-labelled ∧ isolate) — purely
 // client-side, applied on top of the colours the semantic state produces.
-const vis = { hideLabeled: false, hiddenClasses: new Set(), isolate: false };
+const vis = { hideLabeled: false, hiddenClasses: new Set(), isolate: false, hiddenCount: 0 };
 
 // -- themes ------------------------------------------------------------------
 
@@ -563,6 +575,10 @@ async function doSave() {
 }
 
 function applyState(raw) {
+  // Label edits (assign / undo / redo / group assigns) come back as a delta —
+  // just the touched indices and values — so applying them stays O(edit)
+  // whatever the cloud size. Everything else carries the full arrays.
+  if (raw.labels_delta && state && cloud.xyz) return applyDelta(raw);
   state = {
     snapshot: raw.snapshot,
     labels: decodeArray(raw.labels),
@@ -571,6 +587,29 @@ function applyState(raw) {
   };
   if (state.selection.length === 0) vis.isolate = false; // isolate is armed per-selection
   refreshColors();
+  finishStateRender();
+}
+
+function applyDelta(raw) {
+  const indices = decodeArray(raw.labels_delta.indices);
+  const values = decodeArray(raw.labels_delta.values);
+  const oldSelection = state.selection;
+  const wasIsolate = vis.isolate && oldSelection.length > 0;
+  state.snapshot = raw.snapshot;
+  state.selection = decodeArray(raw.selection);
+  for (let k = 0; k < indices.length; k++) state.labels[indices[k]] = values[k];
+  if (state.selection.length === 0) vis.isolate = false;
+
+  // Isolate couples every point's alpha to the selection as a whole — a
+  // selection change under isolate is a wholesale visibility change, not a
+  // delta. Rare enough to just recompute fully.
+  if (wasIsolate || (vis.isolate && state.selection.length > 0)) refreshColors();
+  else patchColors(indices, oldSelection);
+  finishStateRender();
+}
+
+// The panel/status re-render both state paths share.
+function finishStateRender() {
   viewer.setHighlight(state.selection, cloud.xyz);
   renderClasses();
   renderModes();
@@ -581,6 +620,44 @@ function applyState(raw) {
     `Sel: ${state.selection.length.toLocaleString()} · Class: ${className(s.active_class)} · View: ${s.display_mode}`;
 }
 
+// Delta recolour: rewrite only the touched points' colours in the live GPU
+// arrays, re-evaluate visibility for the points it can have changed on (the
+// touched points, plus both selections — selected points are force-visible,
+// so selection churn shows/hides them), and upload just those ranges.
+function patchColors(touched, oldSelection) {
+  const { colors, alpha } = viewer.colorArrays();
+  const colorize = makeLabelColorizer(state, cloud);
+  if (colorize) for (let k = 0; k < touched.length; k++) colorize(colors, touched[k]);
+
+  if (vis.hideLabeled || vis.hiddenClasses.size > 0) {
+    const labels = state.labels;
+    const unlabeled = state.snapshot.unlabeled_id;
+    const selected = new Set(state.selection);
+    // Idempotent per point, so overlap between the three sets double-counts
+    // nothing: the second visit sees before === after.
+    const reapply = (i) => {
+      const before = alpha[i];
+      const masked =
+        (vis.hideLabeled && labels[i] !== unlabeled) || vis.hiddenClasses.has(labels[i]);
+      const after = masked && !selected.has(i) ? 0 : 1;
+      alpha[i] = after;
+      vis.hiddenCount += (after === 0 ? 1 : 0) - (before === 0 ? 1 : 0);
+    };
+    for (let k = 0; k < touched.length; k++) reapply(touched[k]);
+    for (let k = 0; k < oldSelection.length; k++) reapply(oldSelection[k]);
+    for (let k = 0; k < state.selection.length; k++) reapply(state.selection[k]);
+    renderVisPill(vis.hiddenCount);
+  }
+
+  // Selection points' alpha may have changed even when nothing is "touched"
+  // colour-wise — commit the union.
+  const union = new Uint32Array(touched.length + oldSelection.length + state.selection.length);
+  union.set(touched, 0);
+  union.set(oldSelection, touched.length);
+  union.set(state.selection, touched.length + oldSelection.length);
+  viewer.commitColors(union);
+}
+
 // -- point visibility ---------------------------------------------------------
 
 // Recompute colours from the semantic state, apply the visibility mask on top,
@@ -617,6 +694,7 @@ function applyVisibility(alpha) {
       }
     }
   }
+  vis.hiddenCount = hidden; // the delta path adjusts this incrementally
   renderVisPill(hidden);
 }
 

toaster/web/js/colors.js

@@ -37,15 +37,16 @@ function turbo(t) {
 }
 
 // decoded: { snapshot, labels:Int32Array, grouping:Int32Array|null }
-// cloud:   { xyz:Float32Array, features:{ intensity?:Float32Array } }
-export function computeColors(decoded, cloud) {
+// Per-point colour writer for the label-dependent display modes, or null when
+// the current mode's colours can't be changed by a label edit (intensity /
+// height ramps). This is the single source of the per-point rules: the full
+// recompute below and the delta recolour in app.js both call it, so they can
+// never drift apart.
+// decoded: { snapshot, labels:Int32Array, grouping:Int32Array|null }
+export function makeLabelColorizer(decoded, cloud) {
   const snap = decoded.snapshot;
   const labels = decoded.labels;
   const grouping = decoded.grouping;
-  const n = labels.length;
-  const colors = new Float32Array(n * 3);
-  const alpha = new Float32Array(n).fill(1); // every point stays visible & pickable
-
   const mode = snap.display_mode;
   if (mode === "grouping" && grouping) {
     // Segments toggled off (Hide all / Solo / a row's checkbox) are not removed —
@@ -56,22 +57,36 @@ export function computeColors(decoded, cloud) {
     const lut = {};
     for (const c of snap.classes) lut[c.id] = c.color;
     const unlabeled = snap.unlabeled_id;
-    for (let i = 0; i < n; i++) {
+    return (colors, i) => {
       const g = grouping[i];
       if (!hidden.has(g)) setRGB(colors, i, g < 0 ? NOISE : GROUP_PALETTE[g % GROUP_PALETTE.length]);
       else if (labels[i] !== unlabeled) setRGB(colors, i, lut[labels[i]] || DIM);
       else setRGB(colors, i, DIM);
-    }
-  } else if (mode === "intensity" && cloud.features.intensity) {
-    rampInto(colors, cloud.features.intensity);
-  } else if (mode === "height") {
+    };
+  }
+  // Same fall-through as the full recompute: "intensity" without the feature
+  // renders as labels, so it *does* depend on them.
+  if ((mode === "intensity" && cloud.features.intensity) || mode === "height") return null;
+  const lut = {};
+  for (const c of snap.classes) lut[c.id] = c.color;
+  return (colors, i) => setRGB(colors, i, lut[labels[i]] || UNKNOWN);
+}
+
+// cloud:   { xyz:Float32Array, features:{ intensity?:Float32Array } }
+export function computeColors(decoded, cloud) {
+  const n = decoded.labels.length;
+  const colors = new Float32Array(n * 3);
+  const alpha = new Float32Array(n).fill(1); // every point stays visible & pickable
+
+  const colorize = makeLabelColorizer(decoded, cloud);
+  if (colorize) {
+    for (let i = 0; i < n; i++) colorize(colors, i);
+  } else if (decoded.snapshot.display_mode === "height") {
     const z = new Float32Array(n);
     for (let i = 0; i < n; i++) z[i] = cloud.xyz[i * 3 + 2];
     rampInto(colors, z);
   } else {
-    const lut = {};
-    for (const c of snap.classes) lut[c.id] = c.color;
-    for (let i = 0; i < n; i++) setRGB(colors, i, lut[labels[i]] || UNKNOWN);
+    rampInto(colors, cloud.features.intensity);
   }
   return { colors, alpha };
 }

toaster/web/js/viewer.js

@@ -25,6 +25,27 @@ const OCTREE_MIN_POINTS = 200_000;
 // pixels — below it, the node's own sample is already ~1 point per pixel.
 const OCTREE_SPLIT_PX = 110;
 
+// Sort a delta's indices and merge them into [start, count] runs, bridging
+// gaps below 512 slots (uploading a few unchanged points is cheaper than
+// another bufferSubData call). Returns null when the result is still too
+// fragmented — the caller should full-upload instead.
+function coalesceRuns(indices) {
+  if (indices.length === 0) return [];
+  const sorted = Uint32Array.from(indices).sort();
+  const runs = [];
+  let start = sorted[0], prev = sorted[0];
+  for (let k = 1; k < sorted.length; k++) {
+    const v = sorted[k];
+    if (v - prev > 512) {
+      runs.push([start, prev - start + 1]);
+      start = v;
+    }
+    prev = v;
+  }
+  runs.push([start, prev - start + 1]);
+  return runs.length > 64 ? null : runs;
+}
+
 const VERT = `
   attribute vec3 acolor;
   attribute float aalpha;
@@ -251,6 +272,36 @@ export class Viewer {
     this._requestRender();
   }
 
+  // The live GPU-side arrays, for in-place patching by the delta recolour.
+  // Write into them, then call commitColors with the touched indices.
+  colorArrays() {
+    return {
+      colors: this.geom.getAttribute("acolor").array,
+      alpha: this.geom.getAttribute("aalpha").array,
+    };
+  }
+
+  // Upload only what a label delta touched: the indices are coalesced into a
+  // few contiguous ranges (lidar points arrive in scan order, so a labelled
+  // cluster is usually index-local too). Falls back to a full upload when the
+  // edit is too scattered for ranged updates to win.
+  commitColors(indices) {
+    const ca = this.geom.getAttribute("acolor");
+    const aa = this.geom.getAttribute("aalpha");
+    const runs = coalesceRuns(indices);
+    if (runs && ca.addUpdateRange) {
+      ca.clearUpdateRanges();
+      aa.clearUpdateRanges();
+      for (const [start, count] of runs) {
+        ca.addUpdateRange(start * 3, count * 3);
+        aa.addUpdateRange(start, count);
+      }
+    }
+    ca.needsUpdate = true;
+    aa.needsUpdate = true;
+    this._requestRender();
+  }
+
   setHighlight(indices, xyz) {
     if (this.highlight) {
       this.scene.remove(this.highlight);