concertina 1.0.0 → 1.1.0

package/README.md

@@ -609,6 +609,32 @@ computedWidth = fixedWidth ?? (maxContentChars × charWidthHint + CELL_H_PADDING
 
 `CELL_H_PADDING` is 16 px. A 14 px monospace font uses `charWidthHint: 8`. Widths are resolved once at `INIT` and re-sent with every `WINDOW_UPDATE`.
 
+### DOM-traced pitch
+
+The worker computes a `rowHeight` from `rowHeightHint` at `INIT` time, but real rows may be taller due to padding, borders, or font metrics that differ from the hint. **Pitch** lets the main thread override the worker's row height with a DOM-measured value.
+
+```tsx
+// Measure actual row height from the DOM (e.g. from a ghost/warmup row)
+const [measuredPitch, setMeasuredPitch] = useState(0);
+const ghostRef = useCallback((el) => {
+  if (el) setMeasuredPitch(el.getBoundingClientRect().height);
+}, []);
+
+// Push to the store — VirtualChamber and scroll handler read it automatically
+useEffect(() => {
+  if (measuredPitch > 0) store.setPitch(measuredPitch);
+}, [measuredPitch, store]);
+```
+
+When `pitch > 0`, VirtualChamber uses it instead of `layout.rowHeight` for:
+- **Spacer height**: `totalRows × pitch` (scrollbar range)
+- **Pool node height**: each pool `<div>` gets `height: pitch`
+- **translateY**: row positioning uses `rowIndex × pitch`
+- **Scroll handler**: `SET_WINDOW` start row = `Math.floor(scrollTop / pitch)`
+- **scrollToRow**: programmatic scroll uses `row × pitch`
+
+When `pitch` is `0` (the default), all math falls back to the worker's `layout.rowHeight`. This means existing code that doesn't call `setPitch` continues to work unchanged.
+
 ---
 
 ## License

package/dist/core/data-worker.js

@@ -29,7 +29,8 @@ var INITIAL_STORE_STATE = {
   window: null,
   backpressure: { strategy: "NOMINAL", queueDepth: 0, avgRenderMs: asMs(0) },
   totalRows: 0,
-  error: null
+  error: null,
+  pitch: 0
 };
 
 // src/core/data-worker.ts

package/dist/core/index.cjs

@@ -74,7 +74,8 @@ var INITIAL_STORE_STATE = {
   window: null,
   backpressure: { strategy: "NOMINAL", queueDepth: 0, avgRenderMs: asMs(0) },
   totalRows: 0,
-  error: null
+  error: null,
+  pitch: 0
 };
 
 // src/core/atomic-store.ts
@@ -127,6 +128,10 @@ var AtomicStore = class {
   setStatus(status, error) {
     this.merge({ status, error: error ?? this.state.error });
   }
+  /** Set DOM-traced row pitch. 0 resets to Worker-computed rowHeight. */
+  setPitch(px) {
+    if (this.state.pitch !== px) this.merge({ pitch: px });
+  }
   merge(patch) {
     const next = { ...this.state, ...patch };
     this.state = next;
@@ -228,14 +233,16 @@ function useStabilityOrchestrator(options) {
     const el = containerRef_internal.current;
     const lay = layoutRef.current;
     if (!el || !lay || lay.rowHeight === 0) return;
-    const startRow = asRowIndex(Math.floor(el.scrollTop / lay.rowHeight));
+    const p = store.getState().pitch;
+    const rh = p > 0 ? p : lay.rowHeight;
+    const startRow = asRowIndex(Math.floor(el.scrollTop / rh));
     const rowCount = lay.viewportRows + overscanRows * 2;
     workerRef.current?.postMessage({
       type: "SET_WINDOW",
       startRow,
       rowCount
     });
-  }, [overscanRows]);
+  }, [overscanRows, store]);
   const containerRef = (0, import_react2.useCallback)(
     (el) => {
       if (containerRef_internal.current) {
@@ -322,13 +329,15 @@ function useStabilityOrchestrator(options) {
     const el = containerRef_internal.current;
     const lay = layoutRef.current;
     if (!el || !lay) return;
-    el.scrollTo({ top: row * lay.rowHeight, behavior: "smooth" });
+    const p = store.getState().pitch;
+    const rh = p > 0 ? p : lay.rowHeight;
+    el.scrollTo({ top: row * rh, behavior: "smooth" });
     workerRef.current?.postMessage({
       type: "SET_WINDOW",
       startRow: asRowIndex(Math.max(0, row - overscanRows)),
       rowCount: lay.viewportRows + overscanRows * 2
     });
-  }, [overscanRows]);
+  }, [overscanRows, store]);
   return (0, import_react2.useMemo)(
     () => ({ containerRef, store, ingest, scrollToRow }),
     [containerRef, store, ingest, scrollToRow]
@@ -428,7 +437,7 @@ function buildRowProxy(accessors, schema, localRow) {
     }
   };
 }
-function buildPoolAssignments(win, layout, poolSize) {
+function buildPoolAssignments(win, rowHeight, poolSize) {
   const assignments = [];
   for (let i = 0; i < win.rowCount; i++) {
     const rowIndex = win.startRow + i;
@@ -436,7 +445,7 @@ function buildPoolAssignments(win, layout, poolSize) {
       poolSlot: asPoolSlot(i % poolSize),
       rowIndex: asRowIndex(rowIndex),
       localIndex: i,
-      y: rowIndex * layout.rowHeight
+      y: rowIndex * rowHeight
     });
   }
   return assignments;
@@ -445,14 +454,16 @@ var OVERSCAN_ROWS = 3;
 function VirtualChamber({ store, renderRow, containerRef, className, style }) {
   const layout = useAtomicSlice(store, (s) => s.layout);
   const win = useAtomicSlice(store, (s) => s.window);
+  const pitch = useAtomicSlice(store, (s) => s.pitch);
   const accessors = (0, import_react3.useMemo)(
     () => win ? buildAccessors(win.buffer, win.rowCount) : null,
     [win]
   );
   const poolSize = layout ? layout.viewportRows + OVERSCAN_ROWS * 2 : 0;
+  const rh = (pitch && pitch > 0 ? pitch : layout?.rowHeight) ?? 0;
   const assignments = (0, import_react3.useMemo)(
-    () => win && layout ? buildPoolAssignments(win, layout, poolSize) : [],
-    [win, layout, poolSize]
+    () => win && rh > 0 ? buildPoolAssignments(win, rh, poolSize) : [],
+    [win, rh, poolSize]
   );
   if (!layout) return null;
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
@@ -471,7 +482,7 @@ function VirtualChamber({ store, renderRow, containerRef, className, style }) {
           "div",
           {
             "aria-hidden": true,
-            style: { height: layout.totalHeight, pointerEvents: "none" }
+            style: { height: layout.totalRows * rh, pointerEvents: "none" }
           }
         ),
         accessors !== null && assignments.map(({ poolSlot, rowIndex, localIndex, y }) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
@@ -484,7 +495,7 @@ function VirtualChamber({ store, renderRow, containerRef, className, style }) {
               top: 0,
               left: 0,
               right: 0,
-              height: layout.rowHeight,
+              height: rh,
               transform: `translateY(${y}px)`,
               willChange: "transform",
               contain: "layout style"

package/dist/core/index.d.cts

@@ -136,6 +136,8 @@ interface StoreState {
     readonly backpressure: BackpressureState;
     readonly totalRows: number;
     readonly error: string | null;
+    /** DOM-traced row pitch in px. 0 = use layout.rowHeight from Worker. */
+    readonly pitch: number;
 }
 
 /**
@@ -156,6 +158,8 @@ declare class AtomicStore {
     dispatch(event: WorkerEvent): void;
     /** Transition stream lifecycle status. */
     setStatus(status: StreamStatus, error?: string): void;
+    /** Set DOM-traced row pitch. 0 resets to Worker-computed rowHeight. */
+    setPitch(px: number): void;
     private merge;
 }
 type EqualityFn<T> = (a: T, b: T) => boolean;

package/dist/core/index.d.ts

@@ -136,6 +136,8 @@ interface StoreState {
     readonly backpressure: BackpressureState;
     readonly totalRows: number;
     readonly error: string | null;
+    /** DOM-traced row pitch in px. 0 = use layout.rowHeight from Worker. */
+    readonly pitch: number;
 }
 
 /**
@@ -156,6 +158,8 @@ declare class AtomicStore {
     dispatch(event: WorkerEvent): void;
     /** Transition stream lifecycle status. */
     setStatus(status: StreamStatus, error?: string): void;
+    /** Set DOM-traced row pitch. 0 resets to Worker-computed rowHeight. */
+    setPitch(px: number): void;
     private merge;
 }
 type EqualityFn<T> = (a: T, b: T) => boolean;

package/dist/core/index.js

@@ -42,7 +42,8 @@ var INITIAL_STORE_STATE = {
   window: null,
   backpressure: { strategy: "NOMINAL", queueDepth: 0, avgRenderMs: asMs(0) },
   totalRows: 0,
-  error: null
+  error: null,
+  pitch: 0
 };
 
 // src/core/atomic-store.ts
@@ -95,6 +96,10 @@ var AtomicStore = class {
   setStatus(status, error) {
     this.merge({ status, error: error ?? this.state.error });
   }
+  /** Set DOM-traced row pitch. 0 resets to Worker-computed rowHeight. */
+  setPitch(px) {
+    if (this.state.pitch !== px) this.merge({ pitch: px });
+  }
   merge(patch) {
     const next = { ...this.state, ...patch };
     this.state = next;
@@ -195,14 +200,16 @@ function useStabilityOrchestrator(options) {
     const el = containerRef_internal.current;
     const lay = layoutRef.current;
     if (!el || !lay || lay.rowHeight === 0) return;
-    const startRow = asRowIndex(Math.floor(el.scrollTop / lay.rowHeight));
+    const p = store.getState().pitch;
+    const rh = p > 0 ? p : lay.rowHeight;
+    const startRow = asRowIndex(Math.floor(el.scrollTop / rh));
     const rowCount = lay.viewportRows + overscanRows * 2;
     workerRef.current?.postMessage({
       type: "SET_WINDOW",
       startRow,
       rowCount
     });
-  }, [overscanRows]);
+  }, [overscanRows, store]);
   const containerRef = useCallback2(
     (el) => {
       if (containerRef_internal.current) {
@@ -289,13 +296,15 @@ function useStabilityOrchestrator(options) {
     const el = containerRef_internal.current;
     const lay = layoutRef.current;
     if (!el || !lay) return;
-    el.scrollTo({ top: row * lay.rowHeight, behavior: "smooth" });
+    const p = store.getState().pitch;
+    const rh = p > 0 ? p : lay.rowHeight;
+    el.scrollTo({ top: row * rh, behavior: "smooth" });
     workerRef.current?.postMessage({
       type: "SET_WINDOW",
       startRow: asRowIndex(Math.max(0, row - overscanRows)),
       rowCount: lay.viewportRows + overscanRows * 2
     });
-  }, [overscanRows]);
+  }, [overscanRows, store]);
   return useMemo(
     () => ({ containerRef, store, ingest, scrollToRow }),
     [containerRef, store, ingest, scrollToRow]
@@ -397,7 +406,7 @@ function buildRowProxy(accessors, schema, localRow) {
     }
   };
 }
-function buildPoolAssignments(win, layout, poolSize) {
+function buildPoolAssignments(win, rowHeight, poolSize) {
   const assignments = [];
   for (let i = 0; i < win.rowCount; i++) {
     const rowIndex = win.startRow + i;
@@ -405,7 +414,7 @@ function buildPoolAssignments(win, layout, poolSize) {
       poolSlot: asPoolSlot(i % poolSize),
       rowIndex: asRowIndex(rowIndex),
       localIndex: i,
-      y: rowIndex * layout.rowHeight
+      y: rowIndex * rowHeight
     });
   }
   return assignments;
@@ -414,14 +423,16 @@ var OVERSCAN_ROWS = 3;
 function VirtualChamber({ store, renderRow, containerRef, className, style }) {
   const layout = useAtomicSlice(store, (s) => s.layout);
   const win = useAtomicSlice(store, (s) => s.window);
+  const pitch = useAtomicSlice(store, (s) => s.pitch);
   const accessors = useMemo2(
     () => win ? buildAccessors(win.buffer, win.rowCount) : null,
     [win]
   );
   const poolSize = layout ? layout.viewportRows + OVERSCAN_ROWS * 2 : 0;
+  const rh = (pitch && pitch > 0 ? pitch : layout?.rowHeight) ?? 0;
   const assignments = useMemo2(
-    () => win && layout ? buildPoolAssignments(win, layout, poolSize) : [],
-    [win, layout, poolSize]
+    () => win && rh > 0 ? buildPoolAssignments(win, rh, poolSize) : [],
+    [win, rh, poolSize]
   );
   if (!layout) return null;
   return /* @__PURE__ */ jsxs(
@@ -440,7 +451,7 @@ function VirtualChamber({ store, renderRow, containerRef, className, style }) {
           "div",
           {
             "aria-hidden": true,
-            style: { height: layout.totalHeight, pointerEvents: "none" }
+            style: { height: layout.totalRows * rh, pointerEvents: "none" }
           }
         ),
         accessors !== null && assignments.map(({ poolSlot, rowIndex, localIndex, y }) => /* @__PURE__ */ jsx(
@@ -453,7 +464,7 @@ function VirtualChamber({ store, renderRow, containerRef, className, style }) {
               top: 0,
               left: 0,
               right: 0,
-              height: layout.rowHeight,
+              height: rh,
               transform: `translateY(${y}px)`,
               willChange: "transform",
               contain: "layout style"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "concertina",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "React toolkit for layout stability.",
   "type": "module",
   "main": "./dist/index.cjs",