docs(tutorial): default to precomputed mask + guard against empty segmentation

[xuefei-wang]

Problem

A user reported that "the cell type prediction result appears empty" on the tutorial. The currently-published outputs render fine, but walking the tutorial as a fresh user surfaced the real failure mode:

• The tutorial's primary path builds the mask with cellSAM, and the only post-segmentation check verifies mask shape (mask.shape == img.shape[1:]).
• An all-background / degenerate mask (easy to hit: CPU-only, OOM, the "arbitrary" membrane_channel, or a cellSAM version mismatch) has the correct shape and passes that check.
• predict() then returns [] for a mask with no cells, so the cell-type DataFrame renders empty — exactly the reported symptom, with no error to explain it.

Changes

docs/site/tutorial.md:

1. Default to the archive's pre-computed CellSAM mask (ds["segmentations/cellsam"]) so the pipeline runs end-to-end without a local segmentation setup (no cellSAM/GPU required).
2. Sanity-check shape and cell count — fail loudly instead of silently producing empty predictions:

   assert mask.shape == img.shape[1:], "mask shape does not match the image H, W"
   assert mask.max() > 0, "segmentation mask contains no cells"

3. Keep the cellSAM path intact but optional/reference-only — same code, retitled with an "optional, not executed" note and switched from {code-cell} to plain code blocks, so the docs build no longer requires cellSAM and can't overwrite the default mask.

Net: the "empty prediction result" symptom can no longer occur silently, and the tutorial is completable without a GPU/cellSAM.

Verification

• Docs build succeeds with the new structure (nb_execution_mode=off structure check passes; cellsam_pipeline no longer appears in any executed input cell).
• The default execution path was run end-to-end on CPU: ds["segmentations/cellsam"] → relabel_sequential → predict(...) returns a populated list of 1646 labels, and the DataFrame renders non-empty. The two new asserts pass trivially (shape matches, max=1646 > 0).

🤖 Generated with Claude Code

[rossbar]

We do not want to replace the computation here - the point of the example is to demonstrate a full end-to-end (i.e. raw image -> segmentation -> celltype prediction) pipeline. Note also that this serves as the only real test that the components of this package are working as expected.

[xuefei-wang]

@rossbar Agreed — closing this in favor of #55, which keeps the computation in place.

#55 leaves the raw image → cellSAM → cell-type prediction path fully executed and instead:

1. Restores the two nim.screenshot cells and their <img> embeds, which master had replaced with prose ("Static documentation builds do not execute or embed GUI screenshots") — so the docs build exercises the visualization step again, as it did at 616d4b5.
2. Turns the post-segmentation shape check into a hard assert and adds assert mask.max() > 0, which is what the original report ("the cell type prediction result appears empty") actually needed: a degenerate all-background mask has the correct shape, passes the old check, and yields [] from predict() with nothing to explain it.

This PR is also unmergeable independent of the review — its merge base is 616d4b5, so GitHub reports it as 144 files / ~47k lines against master rather than a docs change. #55 is branched from current master and touches docs/site/tutorial.md only.

[xuefei-wang]

Superseded by #55.