[guijacquemet]

Owner feedback from the v0.5.2 Colab test (12 November 2026, release PR #290). Based on main at ac2dc27. #290 is not touched; it needs a rebuild after this PR merges.

1. The click shows at once ("it feels like nothing is happening")

• Confirm these axes, Confirm axis roles and Change axis roles now disable the button and set it to Working…. The folder check's progress line (notebook_progress.Wait) appears in the same card before any work starts. It then moves through the 5 parts of the confirmation, with a bar and "n of 5" plus a label: checking the roles against every image, redrawing the example, reading the pixel sizes, preparing the run, and preparing Channels/Masks/Check and save. Both are cleared when the work is done. A disabled button still does nothing.
• Widget state is sent to the page as soon as it is set, the same mechanism the folder check's bar uses, so the line shows while the handler runs. The button stays disabled until the end, which also stops a second click from undoing the confirmation.

2. Why it was slow, and the fix

I profiled on owner-like data: 28 images of 3 × 2048² uint16, pixel sizes differing in the 5th decimal, built in a temp folder.

• The cause: each click read every channel of every folder's first image, to fill the per-folder image-type rows. Those rows sit folded under Set per folder…, so nobody saw them. With one image per folder that was 84 of the 93 full-plane reads. The click also rebuilt the Design pairing editor just to attach pictures that the stepper never shows.
• The fix:
  • The rows read their pictures only once Set per folder… is opened. Their answers, cells and refusals are unchanged.
  • The editor is no longer rebuilt where the stepper's viewer replaces its pictures.
• Nothing that is validated changed.

28 folders × 1 image, 3×2048² (local SSD, warm cache)	main	this PR
plane reads per click	93 (~744 MiB)	9 (~72 MiB)
widgets built per click	1,439	1,037
click wall time, median of 3	1.05 s (quick) / 1.17 s (roles)	0.25 s / 0.24 s
time to the first visible change	1,050 ms (quick: nothing until the end)	< 1 ms (Working…)

For 4 folders × 7 images: 21 → 9 reads, 299 → 233 widgets. On Colab with the data on Drive, the reads and the widget traffic cost much more than on a local disk. That is consistent with the owner's report, but I did not measure it on Colab.

3. The image type: proposed at the scan, confirmed on Channels

• Quick scan / Images: display only, from the headers. Before the check it shows the type of the image on screen; after the check it shows the type from every header ("proposed from the headers: colour (RGB) in all 4 images", or "the image headers differ: …" plus R_HETEROGENEOUS_LAYOUT_NOT_ENABLED). Nothing is recorded at the scan.
• Channels: the Image type card comes first on the page, before the stains. Every rule is unchanged:
  • pre-filled only when every header agrees;
  • recorded only by Use for all folders or a per-folder click;
  • Set per folder… when the headers differ;
  • mixed types refused.
• Axes: no image type. The step is done once the roles are confirmed. Channels is done once the type is answered and the channels are tagged.
• Fov.image_type and the published description keep their meaning. The single-column layout and the "every disabled action says why" rule are kept.

4. Published output is unchanged

I gave the same answers through the stepper on main and on this branch, on the same input folders: save, run, and (for the fluorescence experiment) describe the masks.

file	fluorescence (+ masks)	RGB
morphobricks.toml	byte-identical	byte-identical
plane_histograms.csv	byte-identical	byte-identical
experiment_design.csv	byte-identical	byte-identical
calibration.csv	byte-identical	byte-identical
mask_relationships.json, mask_representation.json	byte-identical	(no masks)
run_manifest.json without times and paths	identical	identical

discovery_report.* differ only in the manifest SHA-256 and the output folder path.

5. Embedding API

tests/test_embedding_api.py passes unchanged. confirm_button, check_button, folder_step and axis_step are the same objects and signatures, and handlers that embedders add to confirm_button still run after the confirmation.

Tests

New tests/test_notebook_axes_working.py (9 tests). All 9 fail on main and pass here:

• the working state, a disabled button with a Working… progress line, is set before the first work (review_axes), for both buttons;
• the bar advances through every part, and its width only grows;
• Change axis roles also shows Working…;
• a disabled button does nothing;
• confirming reads no picture for the folded rows, and opening them reads the pictures;
• the image type is not on Axes, comes before the stains on Channels, and is recorded only by the click;
• it is proposed at the scan with nothing recorded, and headers that differ are reported.

I updated these existing tests to the new placement: test_notebook_stepper, test_notebook_seven_steps, test_notebook_tag_blocks, test_notebook_stains_na, and test_notebook_colour (it now opens Set per folder… before looking at the pictures).

Docs

CHANGELOG.md (Unreleased), docs/colab-release-check.md (image type on Channels; Working… and the bar on Axes), the notebook's step list, and docs/contract.md §13.

Gate

python tools/check.py: Ruff clean, code rules clean, 5485 passed, 4 skipped. The skips are environment-only:

• 3 × "this file system tells names apart by case";
• 1 × "running with permissions that ignore file modes".

Screenshots, before and after, are in the session scratchpad (v052fix-shots/).

---

Generated by Claude Code

[guijacquemet]

Independent review of 05c0b4f, from a fresh clone and venv.

One defect, fixed in ec04490 with a regression test that fails before the fix. If the confirmation raised part-way (for example in preparing the run), _working gave the button back but showed nothing. The progress line was cleared, the status above still said "Axes checked", and after Confirm these axes the one-click card had already hidden. Now the failure is caught: the button is re-enabled as before, the error appears in red under the button that was clicked (under Confirm axis roles once the one-click card is gone), and the traceback goes to Technical details, as the run and the mask step already do. Test: test_a_failure_part_way_gives_the_button_back_and_shows_the_error[quick|roles]. A CHANGELOG line was added under Unreleased.

Verified, no change needed

• Working state: both buttons are disabled and say Working… before review_axes runs. The bar shows 0 to 4 of 5 with labels, then clears. A disabled button does nothing.

• Timings, with measure_confirm_click.py (28 folders, 3×2048² uint16, local disk, median of 3):

  	main	05c0b4f	ec04490
  quick: click time	0.98 s	0.18 s	0.20 s
  roles: click time	1.03 s	0.16 s	0.19 s
  plane reads	93	9	9
  widgets built	1,249	847	847
  first visible change, quick	982 ms	0.1 ms	0.1 ms

  The widget counts differ from the PR body's because the test data differ; the read counts match.

• Lazy rows: a row can only be answered while Set per folder… is open. Opening it rebuilds the rows with their pictures, and headers that differ open it automatically. Use for all folders never needed per-folder pictures, on main or here. So no per-folder answer can be recorded without its picture.

• Image type, after the stains are named: switching all folders to RGB sets every unit to R/G/B. Switching back clears all tags (12 to re-tag), and R/G/B leave the declared channels. This is identical to main's behaviour, checked with the same probe on both.

• Byte identity: the same answers were given through the stepper on main and on ec04490 (save + run), for one fluorescence experiment and one RGB experiment, both with masks. morphobricks.toml, experiment_design.csv and plane_histograms.csv are byte-identical. run_manifest.json differs only in written_at. discovery_report.* differ only in the manifest SHA and the output path.

• Embedding API: the public PreprocessingNotebook signatures are identical to main's. In embedded use (no stepper), check_viewer is None, so the editor is still rebuilt there.

• Gate: python tools/check.py on ec04490 passed: Ruff and code rules clean, 5487 passed, 4 skipped (environment only: 3 case-insensitive-FS, 1 file-mode).

For the owner (unchanged from main): after stains are named, switching every folder to RGB keeps the declared stains as "saved, unused". The card says so, and they are still written to [channels.*] in morphobricks.toml (W_UNUSED_CHANNEL).

---

Generated by Claude Code