@jbrowse/render-core 5.0.0-beta.1 → 5.0.0-beta.2

package/esm/RenderLifecycleMixin.d.ts

@@ -95,11 +95,11 @@ export declare function RenderLifecycleMixin(): import("@jbrowse/mobx-state-tree
      * never called and `canvasDrawn` can never flip).
      *
      * Lives here, beside `canvasDrawn`, because every consumer of "has this
-     * display painted" needs the pair — and until 2026-08 each family
-     * declared its own copy (per-region hard-coded `true`, global carried the
-     * hook for LD), so a display could express the state only to whichever
-     * family it happened to compose. See `painted` below for the reader that
-     * was missed.
+     * display painted" needs the pair. Both LGV fetch foundations fill it
+     * with `!fetchInert`, so a display there states its placeholder once,
+     * through that hook; the raw default reaches only a display composing
+     * this mixin outside them. See `painted` below for the reader that was
+     * missed while the two were separate overrides.
      */
     readonly rendersCanvas: boolean;
     /**

package/esm/RenderLifecycleMixin.js

@@ -104,11 +104,11 @@ export function RenderLifecycleMixin() {
          * never called and `canvasDrawn` can never flip).
          *
          * Lives here, beside `canvasDrawn`, because every consumer of "has this
-         * display painted" needs the pair — and until 2026-08 each family
-         * declared its own copy (per-region hard-coded `true`, global carried the
-         * hook for LD), so a display could express the state only to whichever
-         * family it happened to compose. See `painted` below for the reader that
-         * was missed.
+         * display painted" needs the pair. Both LGV fetch foundations fill it
+         * with `!fetchInert`, so a display there states its placeholder once,
+         * through that hook; the raw default reaches only a display composing
+         * this mixin outside them. See `painted` below for the reader that was
+         * missed while the two were separate overrides.
          */
         get rendersCanvas() {
             return true;

package/esm/contractReports.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A contract family — the `<family>` in the `[jbrowse <family> contract]`
+ * prefix every contract check in the tree reports under.
+ * `config/jest/console.js` matches `\w+`, so a new one reaches the test gate
+ * without touching it.
+ */
+export type ContractFamily = 'display' | 'session' | 'figure';
+export interface ContractReport {
+    family: ContractFamily;
+    message: string;
+    /** what armed the channel, so a host can say why it is showing this */
+    armedBy: string;
+}
+/**
+ * Whether the checks should run at all.
+ *
+ * Read it where a check costs something to run — the `MutationObserver` a live
+ * figure installs, the per-frame payload walk in `installUpload`. A check whose
+ * cost is a `WeakSet` lookup should run unconditionally and report through
+ * {@link reportContractViolation} instead, so that arming the channel late
+ * still surfaces what it found.
+ */
+export declare function contractReportsOn(): boolean;
+/**
+ * Turn the channel on in a production build, saying what turned it on.
+ *
+ * The reason is not decoration: a notification that appears in an app the
+ * reader did not build has to answer "why am I seeing this" in its own text, or
+ * it reads as the app being broken rather than as a plugin being under
+ * development. First caller wins, so the earliest evidence is the one quoted.
+ */
+export declare function enableContractReports(reason: string): void;
+/**
+ * Where a host puts contract violations that reach a user — a session
+ * notification in the apps. Installing one drains whatever was found before the
+ * host existed, and the disposer only clears the sink it installed, so a
+ * session torn down after its replacement was built does not take the live
+ * one's sink with it.
+ */
+export declare function setContractReportSink(fn: (report: ContractReport) => void): () => void;
+/**
+ * Report a violation of an ordering contract no type can state.
+ *
+ * In tree this is the `console.error` it has always been, and the jest gate is
+ * what listens. Out of tree it is the only thing that reaches a plugin author
+ * at all: their display runs in a production build of somebody's app, which
+ * strips nothing here, and a violation surfaces the moment anything arms the
+ * channel — a `localStorage` flag, a plugin loaded from localhost, or a site
+ * whose config asks for it.
+ *
+ * `agent-docs/reference/ARCHITECTURAL_LIMITS.md` §"Ordering is the contract" is
+ * the register of what reports here.
+ */
+export declare function reportContractViolation(family: ContractFamily, message: string): void;

package/esm/contractReports.js

@@ -0,0 +1,112 @@
+const DEVELOPER_MODE_KEY = 'jbrowseDeveloperMode';
+// The flag a plugin author can set on any deployed JBrowse without owning it or
+// asking anyone, which is the population this whole channel is for.
+function storageFlag() {
+    try {
+        return typeof localStorage === 'undefined' ||
+            localStorage.getItem(DEVELOPER_MODE_KEY) === null
+            ? undefined
+            : `localStorage.${DEVELOPER_MODE_KEY} is set`;
+    }
+    catch {
+        // storage can be denied outright, and a diagnostic is not the thing to take
+        // the app down with
+        return undefined;
+    }
+}
+// Module scope for the same reason `numberGrouping` is: a check is called from
+// a mixin factory, an MST action and a React effect that cannot share a
+// closure, and each realm resolves this once at startup rather than through an
+// observable a worker could not see.
+let armedBy = process.env.NODE_ENV === 'production'
+    ? storageFlag()
+    : 'this is a development build';
+let sink;
+const unlogged = [];
+const undelivered = [];
+const PENDING_LIMIT = 20;
+function remember(queue, found) {
+    if (queue.length < PENDING_LIMIT) {
+        queue.push(found);
+    }
+}
+/**
+ * Whether the checks should run at all.
+ *
+ * Read it where a check costs something to run — the `MutationObserver` a live
+ * figure installs, the per-frame payload walk in `installUpload`. A check whose
+ * cost is a `WeakSet` lookup should run unconditionally and report through
+ * {@link reportContractViolation} instead, so that arming the channel late
+ * still surfaces what it found.
+ */
+export function contractReportsOn() {
+    return armedBy !== undefined;
+}
+/**
+ * Turn the channel on in a production build, saying what turned it on.
+ *
+ * The reason is not decoration: a notification that appears in an app the
+ * reader did not build has to answer "why am I seeing this" in its own text, or
+ * it reads as the app being broken rather than as a plugin being under
+ * development. First caller wins, so the earliest evidence is the one quoted.
+ */
+export function enableContractReports(reason) {
+    armedBy ??= reason;
+    for (const found of unlogged.splice(0)) {
+        emit(found, armedBy);
+    }
+}
+/**
+ * Where a host puts contract violations that reach a user — a session
+ * notification in the apps. Installing one drains whatever was found before the
+ * host existed, and the disposer only clears the sink it installed, so a
+ * session torn down after its replacement was built does not take the live
+ * one's sink with it.
+ */
+export function setContractReportSink(fn) {
+    sink = fn;
+    if (armedBy !== undefined) {
+        for (const found of undelivered.splice(0)) {
+            fn({ ...found, armedBy });
+        }
+    }
+    return () => {
+        if (sink === fn) {
+            sink = undefined;
+        }
+    };
+}
+function emit(found, armed) {
+    // `console.error`, never a throw: an error escaping `afterAttach` is read by
+    // the session loader as an invalid track and the display is silently dropped,
+    // which would hide the very violation being reported. The prefix is what
+    // `config/jest/console.js` buffers and `contractGate.js` fails a test on.
+    console.error(`[jbrowse ${found.family} contract] ${found.message}`);
+    if (sink === undefined) {
+        remember(undelivered, found);
+    }
+    else {
+        sink({ ...found, armedBy: armed });
+    }
+}
+/**
+ * Report a violation of an ordering contract no type can state.
+ *
+ * In tree this is the `console.error` it has always been, and the jest gate is
+ * what listens. Out of tree it is the only thing that reaches a plugin author
+ * at all: their display runs in a production build of somebody's app, which
+ * strips nothing here, and a violation surfaces the moment anything arms the
+ * channel — a `localStorage` flag, a plugin loaded from localhost, or a site
+ * whose config asks for it.
+ *
+ * `agent-docs/reference/ARCHITECTURAL_LIMITS.md` §"Ordering is the contract" is
+ * the register of what reports here.
+ */
+export function reportContractViolation(family, message) {
+    if (armedBy === undefined) {
+        remember(unlogged, { family, message });
+    }
+    else {
+        emit({ family, message }, armedBy);
+    }
+}

package/esm/displayPhase.d.ts

@@ -83,6 +83,15 @@ export interface DisplayLoadingInputs {
      * click.
      */
     isLoadingOrCanceled: boolean;
+    /**
+     * A load this display depends on beyond its primary fetch has not landed for
+     * the first time, so the frame the primary fetch calls current is still
+     * missing something (multi-way synteny's lane genes and links). A loading
+     * term rather than a `dataSuperseded` fold: that flag holds the export
+     * through every later refetch too, and a scrim over lanes that are already
+     * drawn is the thing a display saying this wants to avoid.
+     */
+    awaitingDependentData: boolean;
     /**
      * Whether this display paints a canvas in its current configuration. Gates
      * the pre-first-paint term alone, because a display that is showing a
@@ -142,7 +151,7 @@ export interface DisplayLoadingInputs {
  * IntersectionObserver's first callback, which is exactly when a display must
  * not flash `ready`. Only the paint it will never do is excused.
  */
-export declare function computeLoadingTerm({ fetchInert, viewportEmpty, isLoadingOrCanceled, rendersCanvas, canvasDrawn, }: DisplayLoadingInputs, viewportCurrent: () => boolean, hostMounted?: () => boolean): boolean;
+export declare function computeLoadingTerm({ fetchInert, viewportEmpty, isLoadingOrCanceled, awaitingDependentData, rendersCanvas, canvasDrawn, }: DisplayLoadingInputs, viewportCurrent: () => boolean, hostMounted?: () => boolean): boolean;
 /**
  * The same ranking minus `renderError`, for a display with no rendering backend
  * to fail (arc's main-thread SVG). `computeDisplayPhase` delegates here rather

package/esm/displayPhase.js

@@ -70,10 +70,11 @@ export function computeDisplayPhase({ renderError, regionTooLarge, error }, load
  * IntersectionObserver's first callback, which is exactly when a display must
  * not flash `ready`. Only the paint it will never do is excused.
  */
-export function computeLoadingTerm({ fetchInert, viewportEmpty, isLoadingOrCanceled, rendersCanvas, canvasDrawn, }, viewportCurrent, hostMounted = () => true) {
+export function computeLoadingTerm({ fetchInert, viewportEmpty, isLoadingOrCanceled, awaitingDependentData, rendersCanvas, canvasDrawn, }, viewportCurrent, hostMounted = () => true) {
     return (!fetchInert &&
         !viewportEmpty &&
         (isLoadingOrCanceled ||
+            awaitingDependentData ||
             (rendersCanvas && hostMounted() && !canvasDrawn) ||
             !viewportCurrent()));
 }

package/esm/installUpload.js

@@ -1,5 +1,6 @@
 import { getType } from '@jbrowse/mobx-state-tree';
 import { computed } from 'mobx';
+import { contractReportsOn, reportContractViolation, } from './contractReports.js';
 import { createMapUploadSync } from './mapUploadSync.js';
 import { isCheckedAtTheStore } from './regionDataMap.js';
 /**
@@ -29,7 +30,7 @@ function checkPayloads(self, cells) {
             }
             if (!named.has(key)) {
                 named.add(key);
-                console.error(`[jbrowse display contract] ${getType(self).name}: cell ${String(key)} ` +
+                reportContractViolation('display', `${getType(self).name}: cell ${String(key)} ` +
                     `handed to installUpload is \`${String(value)}\`. A fetch answers ` +
                     'a payload or nothing; leave the key out until it has one.');
             }
@@ -51,7 +52,7 @@ export function installUpload(self, backend, { cells, inputs, encode, render })
             return {
                 upload: b => {
                     const current = own();
-                    if (process.env.NODE_ENV !== 'production') {
+                    if (contractReportsOn()) {
                         checkPayloads(self, current);
                     }
                     return sync(b, current);
@@ -66,7 +67,7 @@ export function installUpload(self, backend, { cells, inputs, encode, render })
         return {
             upload: b => {
                 const current = cells();
-                if (process.env.NODE_ENV !== 'production') {
+                if (contractReportsOn()) {
                     checkPayloads(self, current);
                 }
                 const p = props ? props.get() : undefined;

package/esm/regionDataMap.js

@@ -1,4 +1,5 @@
 import { observable } from 'mobx';
+import { reportContractViolation } from './contractReports.js';
 // Maps built here check themselves at the `set`, so the upload seam skips them
 // and a bad entry is reported once, with the field named.
 //
@@ -73,26 +74,27 @@ export function regionDataMap(
 // reached by forgetting rather than by deciding.
 name) {
     const map = observable.map(undefined, { deep: false, name });
-    if (process.env.NODE_ENV !== 'production') {
-        checkedAtTheStore.add(map);
-        const set = map.set.bind(map);
-        map.set = (key, value) => {
-            // as `unknown`, because the claim that this is a `T` is the thing in
-            // doubt — checking it against its own declared type narrows to `never`
-            // and checks nothing
-            const stored = value;
-            if (typeof stored !== 'object' || stored === null) {
-                // `console.error`, never `throw`: the store runs inside the fetch's own
-                // result handler, where a throw is caught and reported as a failed
-                // region — which would hide the violation being reported.
-                console.error(`[jbrowse display contract] ${name}: region ${key} stored ` +
-                    `\`${stored === null ? 'null' : typeof stored}\`, not a ` +
-                    'payload. A fetch RPC answers a payload or a regionTooLarge ' +
-                    'refusal; storing anything else leaves every reader of this map ' +
-                    'reading through it.');
-            }
-            return set(key, value);
-        };
-    }
+    checkedAtTheStore.add(map);
+    const set = map.set.bind(map);
+    // one `typeof` per stored region, which is why it is not gated on the channel
+    // being armed: a violation found in a production build is buffered until
+    // something arms it, where a gate here would have thrown the evidence away
+    map.set = (key, value) => {
+        // as `unknown`, because the claim that this is a `T` is the thing in
+        // doubt — checking it against its own declared type narrows to `never`
+        // and checks nothing
+        const stored = value;
+        if (typeof stored !== 'object' || stored === null) {
+            // reported and never thrown: the store runs inside the fetch's own result
+            // handler, where a throw is caught and reported as a failed region —
+            // which would hide the violation being reported.
+            reportContractViolation('display', `${name}: region ${key} stored ` +
+                `\`${stored === null ? 'null' : typeof stored}\`, not a ` +
+                'payload. A fetch RPC answers a payload or a regionTooLarge ' +
+                'refusal; storing anything else leaves every reader of this map ' +
+                'reading through it.');
+        }
+        return set(key, value);
+    };
     return map;
 }

package/esm/shaders/hpmath.js.generated.d.ts

@@ -1,3 +1,4 @@
 export declare function snapBoxHeightPx(heightPx: number): number;
+export declare function snapBoxTopPx(topY: number, heightPx: number, scrollY: number): number;
 export declare function snapBoxCenterYPx(centerY: number, heightPx: number, scrollY: number): number;
 export declare function extendToMinWidthPx(x1: number, x2: number, minWidth: number): number;

package/esm/shaders/hpmath.js.generated.js

@@ -26,8 +26,11 @@ export function snapBoxHeightPx(heightPx) {
     }
     return _t1;
 }
+export function snapBoxTopPx(topY, heightPx, scrollY) {
+    return Math.floor(((((topY + (heightPx * 0.5)) - (snapBoxHeightPx(heightPx) * 0.5)) - scrollY) + 0.5));
+}
 export function snapBoxCenterYPx(centerY, heightPx, scrollY) {
-    return ((Math.floor((((centerY - (heightPx * 0.5)) - scrollY) + 0.5)) + Math.floor((snapBoxHeightPx(heightPx) * 0.5))) + 0.5);
+    return ((snapBoxTopPx((centerY - (heightPx * 0.5)), heightPx, scrollY) + Math.floor((snapBoxHeightPx(heightPx) * 0.5))) + 0.5);
 }
 export function extendToMinWidthPx(x1, x2, minWidth) {
     let dx = (x2 - x1);

package/esm/shaders/rowRect.generated.d.ts

@@ -1,3 +1,2 @@
 export declare const MIN_DRAWN_ROW_PX = 1;
-export declare const MIN_DRAWN_CELL_PX = 1;
 export declare const MULTI_ROW_MIN_CELL_PX = 2;

package/esm/shaders/rowRect.generated.js

@@ -1,5 +1,4 @@
 // AUTO-GENERATED by packages/shader-tools/src/shader-codegen from rowRect.slang.
 // Do not edit. Run `pnpm gen:shaders` to regenerate.
 export const MIN_DRAWN_ROW_PX = 1;
-export const MIN_DRAWN_CELL_PX = 1;
 export const MULTI_ROW_MIN_CELL_PX = 2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbrowse/render-core",
-  "version": "5.0.0-beta.1",
+  "version": "5.0.0-beta.2",
   "type": "module",
   "description": "GPU/Canvas2D rendering primitives for JBrowse displays: the HAL, the draw-lifecycle mixin, per-region/global backend bases, and the React backend hooks",
   "keywords": [
@@ -31,6 +31,7 @@
     "./canvas2dUtils": "./esm/canvas2dUtils.js",
     "./canvasContext": "./esm/canvasContext.js",
     "./colorRampLut": "./esm/colorRampLut.js",
+    "./contractReports": "./esm/contractReports.js",
     "./coverageBand": "./esm/coverageBand.js",
     "./coverageBandBuffers": "./esm/coverageBandBuffers.js",
     "./createRenderingBackend": "./esm/createRenderingBackend.js",

package/src/shaders/hpmath.js.generated.ts

@@ -26,8 +26,12 @@ export function snapBoxHeightPx(heightPx: number): number {
   return _t1
 }
 
+export function snapBoxTopPx(topY: number, heightPx: number, scrollY: number): number {
+  return Math.floor(((((topY + (heightPx * 0.5)) - (snapBoxHeightPx(heightPx) * 0.5)) - scrollY) + 0.5))
+}
+
 export function snapBoxCenterYPx(centerY: number, heightPx: number, scrollY: number): number {
-  return ((Math.floor((((centerY - (heightPx * 0.5)) - scrollY) + 0.5)) + Math.floor((snapBoxHeightPx(heightPx) * 0.5))) + 0.5)
+  return ((snapBoxTopPx((centerY - (heightPx * 0.5)), heightPx, scrollY) + Math.floor((snapBoxHeightPx(heightPx) * 0.5))) + 0.5)
 }
 
 export function extendToMinWidthPx(x1: number, x2: number, minWidth: number): number {

package/src/shaders/hpmath.slang

@@ -8,7 +8,7 @@
 // must make identically to the GPU — which pixel row a glyph centers on, how a
 // sub-pixel span is widened. `pnpm gen:shaders` transliterates them into
 // hpmath.js.generated.ts; nothing downstream re-derives them by hand.
-//! js-export: snapBoxHeightPx, snapBoxCenterYPx, extendToMinWidthPx
+//! js-export: snapBoxHeightPx, snapBoxTopPx, snapBoxCenterYPx, extendToMinWidthPx
 //! js-skip: hpSplitUint — the hi/lo float32 precision split exists because a GPU has no float64; the Canvas2D path just uses a number
 //! js-skip: quadLocal — maps a vertex id to a quad corner — Canvas2D has no vertices, it calls fillRect
 //! js-skip: yPxToClipY — clip space is the GPU coordinate system; the px-space decision it wraps is what gets exported (snapBoxCenterYPx and friends)
@@ -91,14 +91,27 @@ public float snapBoxHeightPx(float heightPx) {
   return even && hPx >= 2.0 && hPx <= THIN_BOX_PX ? hPx + 1.0 : hPx;
 }
 
+// The pixel row a box's top edge lands on. Snapped about the box's CENTER, not
+// its top: `snapBoxHeightPx` rounds the height and sometimes nudges it a whole
+// pixel, and anchoring the top spends all of that off the BOTTOM edge. A box the
+// layout deliberately centered inside its row then isn't — a UTR is
+// center-shrunk to 0.65 of the transcript body, so at superCompact's 3px row its
+// 1.95px box rounded up to 3px and drew a full pixel below the CDS beside it,
+// while the intron line and strand arrow (which snap to the row's center row)
+// sat on its top edge. Top-anchored and center-anchored agree wherever the
+// height survives the snap unchanged, which is every full-height feature box.
+public float snapBoxTopPx(float topY, float heightPx, float scrollY) {
+  float centerY = topY + heightPx * 0.5;
+  return floor(centerY - snapBoxHeightPx(heightPx) * 0.5 - scrollY + 0.5);
+}
+
 // Center a thin glyph on the *drawn* middle row of the box it annotates, given
-// the box's real center `centerY` and height `heightPx`. The box is rasterized
-// with the rect shader's edge snapping (top = floor(top+0.5), height =
-// snapBoxHeightPx(h)); reproducing that here lands the line/chevron exactly on
-// the box's center row instead of the ~1px bias a plain pixel-center snap
-// (`floor(centerY - scrollY + 0.5) + 0.5`) gives. Thin boxes are drawn at an odd
-// height precisely so that center row exists; a taller even box still has none,
-// and stays consistent (just below the seam).
+// the box's real center `centerY` and height `heightPx`. Reproducing the rect
+// shader's own edge snapping (`snapBoxTopPx` + `snapBoxHeightPx`) lands the
+// line/chevron exactly on the box's center row instead of the ~1px bias a plain
+// pixel-center snap (`floor(centerY - scrollY + 0.5) + 0.5`) gives. Thin boxes
+// are drawn at an odd height precisely so that center row exists; a taller even
+// box still has none, and stays consistent (just below the seam).
 //
 // Split in two on purpose. The decision — which pixel row is the center — is
 // resolution math the Canvas2D and SVG paths need in *screen px*; only the
@@ -107,7 +120,7 @@ public float snapBoxHeightPx(float heightPx) {
 // re-deriving it (see adr-051). Keep new shared decisions in this shape: pure
 // px-in/px-out below, the `yPxToClipY` wrapper above it.
 public float snapBoxCenterYPx(float centerY, float heightPx, float scrollY) {
-  float topPx = floor(centerY - heightPx * 0.5 - scrollY + 0.5);
+  float topPx = snapBoxTopPx(centerY - heightPx * 0.5, heightPx, scrollY);
   return topPx + floor(snapBoxHeightPx(heightPx) * 0.5) + 0.5;
 }
 

package/src/shaders/rowRect.generated.ts

@@ -3,6 +3,4 @@
 
 export const MIN_DRAWN_ROW_PX = 1
 
-export const MIN_DRAWN_CELL_PX = 1
-
 export const MULTI_ROW_MIN_CELL_PX = 2

package/src/shaders/rowRect.slang

@@ -11,13 +11,14 @@
 // Row placement comes from uniforms rather than the instance data, so a
 // rowHeight / rowProportion change re-renders without a refetch.
 //
-// What the callers legitimately differ on is the min-width floor: both the
-// width they write into `minCellPx` and the *unit* they measure it in, via
-// `minCellDenomPx` (CSS px vs device px) — see GpuMafRenderer's note. Those are
-// uniform-write decisions, not a reason for two shaders. The unit is also
-// unsettled, and device px additionally makes MAF's floor depend on the
-// reader's monitor: `agent-docs/ideas/maf-subpixel-cells.md`.
-//! export-consts: MIN_DRAWN_ROW_PX, MIN_DRAWN_CELL_PX, MULTI_ROW_MIN_CELL_PX
+// What the callers legitimately differ on is the min-width floor they write
+// into `minCellPx` — a uniform-write decision, not a reason for two shaders.
+// Whether to floor at all turns on whether the caller's marks TILE: MAF's cells
+// do, so a sub-pixel one is read as part of the run around it and widening it
+// paints ink the alignment does not contain (measured, and MAF now passes 0 —
+// `agent-docs/reference/MAF_SUBPIXEL_CELLS.md`). The multi-row painter's features
+// are sparse intervals with nothing beside them, so it floors.
+//! export-consts: MIN_DRAWN_ROW_PX, MULTI_ROW_MIN_CELL_PX
 //! js-export: drawnRowHeightPx, rowBandOffsetPx
 module rowRect;
 
@@ -36,16 +37,13 @@ public struct RowRectUniforms {
   public float  canvasHeight;  // CSS px
   // The width `minCellPx` is measured against, and so the thing that decides
   // what unit `minCellPx` IS. Named for that rather than for the viewport
-  // because the three callers do not agree: multi-row and wiggle density pass
-  // a CSS width (a 1 CSS px floor), MAF passes a device one (1 device px, so
-  // half a CSS px on a retina screen and a floor that moves with the monitor).
-  // That disagreement is live and parked, not settled —
-  // agent-docs/ideas/maf-subpixel-cells.md — so the name carries it to every
-  // call site instead of a comment forty lines away.
+  // because the callers that floor pass a CSS width. Pass a DEVICE width and
+  // the floor moves with the reader's monitor — MAF did, and rendered
+  // measurably differently on a retina screen until it stopped flooring.
   public float  minCellDenomPx;
-  // Narrowest a cell is painted, in whatever unit `minCellDenomPx` is in.
-  // MIN_DRAWN_CELL_PX is the floor a caller takes when it has no reason to
-  // widen further; the multi-row painter does (see MULTI_ROW_MIN_CELL_PX).
+  // Narrowest a cell is painted, in whatever unit `minCellDenomPx` is in. Zero
+  // is a no-op and is what a tiling caller writes (MAF); the multi-row painter
+  // names its own width, MULTI_ROW_MIN_CELL_PX.
   public float  minCellPx;
   public float  zero;          // always 0.0 — prevents hp-split collapse
   public float  rowHeight;     // CSS px per row
@@ -62,24 +60,16 @@ public struct RowRectVsOut {
   public float4 color    : COLOR0;
 };
 
-// Thinnest a row is ever painted. Vertical twin of MIN_DRAWN_CELL_PX below: a
-// row thinner than a pixel can miss every pixel center and disappear, so
-// without this rows drop out as they get denser instead of just getting
-// thinner. Floored, neighbours overlap instead.
-static const float MIN_DRAWN_ROW_PX = 1.0;
-
-// Thinnest a cell can be painted and still be drawable at all, for the same
-// reason as the row floor above on the other axis. A caller writes this into
-// `minCellPx` when a cell being *visible* is not its problem, only a cell
-// existing; one whose whole encoding is carried by sub-pixel cells asks for
-// more (MULTI_ROW_MIN_CELL_PX).
+// Thinnest a row is ever painted: a row thinner than a pixel can miss every
+// pixel center and disappear, so without this rows drop out as they get denser
+// instead of just getting thinner. Floored, neighbours overlap instead.
 //
-// One caller mirrors it on the Canvas2D side and one deliberately does not: the
-// multi-row painter floors, MAF draws cells at their natural sub-pixel width.
-// That asymmetry is real and parked in `agent-docs/ideas/maf-subpixel-cells.md`;
-// sharing the constant does not decide it, it just stops the value being
-// anonymous in the places that DO agree.
-static const float MIN_DRAWN_CELL_PX = 1.0;
+// There is no X-axis twin. A row is a container the reader is counting, so
+// losing one loses a species; a cell is a sample of a tiling, so losing one to
+// the blend is the honest answer and flooring it invents ink
+// (`agent-docs/reference/MAF_SUBPIXEL_CELLS.md`). The caller that does want an X
+// floor names its own width, below.
+static const float MIN_DRAWN_ROW_PX = 1.0;
 
 // What the multi-row painter ("chromosome painting") writes into `minCellPx`.
 //
@@ -91,9 +81,9 @@ static const float MIN_DRAWN_CELL_PX = 1.0;
 // across two, so neither reaches full opacity — the tick reads as a smudge, and
 // the eye scanning for structure across the rows finds none.
 //
-// Both floors distort width; that is what a floor is. This one distorts more,
-// and only where the alternative was showing nothing legible: a feature wide
-// enough to matter is already past it.
+// A floor distorts width; that is what a floor is. This is the only caller that
+// takes the trade, and only where the alternative was showing nothing legible:
+// a feature wide enough to matter is already past it.
 static const float MULTI_ROW_MIN_CELL_PX = 2.0;
 
 public struct RowBand {