@rivetjs/cdk 0.0.0-stage → 0.1.0-alpha.0

package/masonry/justified.d.ts

@@ -0,0 +1,49 @@
+import { type Geometry } from "./geometry.js";
+export type JustifiedLastRow = "fill" | "justify" | "left" | "center";
+export interface JustifiedOptions {
+    /** Target row height in px (upstream `targetRowHeight`). */
+    rowHeight: number;
+    /** Row heights may vary ± rowHeight · tolerance (upstream `targetRowHeightTolerance`). Default 0.25. */
+    tolerance?: number;
+    /** Edge-case row height bounds (upstream `edgeCaseMinRowHeight` / `edgeCaseMaxRowHeight`). Default 0.5× / 2× `rowHeight`. */
+    minRowHeight?: number;
+    maxRowHeight?: number;
+    /** `[column, row]` gaps (upstream `boxSpacing`). */
+    gap: readonly [number, number];
+    /** Last (widow) row. Default `"fill"`. */
+    lastRow?: JustifiedLastRow;
+}
+/** A row decided at the reference width: item indices, natural (justify) or widow completion. */
+export interface RowPlan {
+    items: number[];
+    /** `justify`: height = (W − (k − 1)·gap) / A, unless clamped at the reference width. `widow`: previous row's height. */
+    kind: "justify" | "widow";
+    style: "justify" | "left" | "center";
+    clamped: number | null;
+}
+/**
+ * Justified rows (Flickr / Google Photos style) of items with aspect ratios `aspects` (width / height; an item weight
+ * multiplies it), decided at container width `refWidth`; geometry in terms of the container width (the breakpoint's
+ * unit with one column).
+ */
+export declare function placeJustified(aspects: ArrayLike<number>, refWidth: number, options: JustifiedOptions): Geometry;
+/** A justified placement plus its row plans (resumable: `placeJustifiedRun(…, { run, from })`). */
+export interface JustifiedRun {
+    geometry: Geometry;
+    /** Rows closed by the greedy pass (before the last-row treatment). */
+    closed: readonly RowPlan[];
+    /** Final rows (after the last-row treatment). */
+    rows: readonly RowPlan[];
+    /** Per final row: top `[k, c]` and height `[k, c]` (linear in W). */
+    rowTop: Float64Array;
+    rowHeight: Float64Array;
+}
+/**
+ * `placeJustified` with a checkpoint: when only items from index `from` on changed (same reference width + options),
+ * the rows closed before the one holding `from` (and before the previous last closed row, which the last-row
+ * treatment may rebalance) are kept with their geometry; the greedy pass restarts there. Equal to a full run.
+ */
+export declare function placeJustifiedRun(aspects: ArrayLike<number>, refWidth: number, options: JustifiedOptions, resume: {
+    run: JustifiedRun;
+    from: number;
+} | null): JustifiedRun;

package/masonry/justified.js

@@ -0,0 +1,250 @@
+// Ported from flickr/justified-layout (lib/row.js, lib/index.js, v4.1.0), MIT, Copyright 2019 SmugMug, Inc.
+// Rivet:
+// - the row packing (`Row.addItem`: min / max aspect ratio window from `targetRowHeight` ± tolerance, the pano special
+//   case, accept-or-reject by distance to the target; `completeLayout`: edge-case clamp to [min, max] row height with
+//   widths kept at the natural height; widows completed at the previous row's height with `widowLayoutStyle`
+//   left / justify / center; center = the row centred in the width) runs at a reference container width and decides the rows; the geometry is then written
+//   as LINEAR terms of the container width W (`./geometry.ts`): a justified row of k items with aspect sum A has height
+//   (W − (k − 1)·gap) / A, so the server CSS fills the width exactly at any W of the breakpoint (no pixel rounding,
+//   upstream's integer error distribution is unnecessary); a row clamped at the reference width keeps the clamped
+//   height (constant) and its natural widths (items crop with `object-fit: cover`, as upstream);
+// - `lastRow: "fill"` (Rivet, the default) rebalances the widow row with the row before it (best split of their items
+//   into one or two justified rows, nearest to the target height, rows inside [minRowHeight, maxRowHeight]) so the
+//   bottom edge is flush and every row fills the width; when no such arrangement exists (a lone portrait, a short
+//   list) the widow stays `left` (upstream default); `"justify"` / `"left"` / `"center"` = upstream `widowLayoutStyle`
+//   (at the previous row's height); a widow wider than the width at that height becomes a justified row (Deviation:
+//   upstream lets it overflow);
+// - not ported: `containerPadding` (the grid has none), `maxNumRows`, `forceAspectRatio`, `fullWidthBreakoutRowCadence`
+//   (breakout rows), `showWidows: false`.
+import { emptyGeometry } from "./geometry.js";
+/** Row.addItem at width `width` (returns [accepted, completedHeight | null]). */
+function addItem(row, aspects, i, width, spacing, target, tolerance) {
+    const minAspectRatio = (width / target) * (1 - tolerance);
+    const maxAspectRatio = (width / target) * (1 + tolerance);
+    const count = row.length + 1;
+    const rowWidthWithoutSpacing = width - (count - 1) * spacing;
+    let newAspectRatio = aspects[i];
+    for (const j of row)
+        newAspectRatio += aspects[j];
+    const targetAspectRatio = rowWidthWithoutSpacing / target;
+    if (newAspectRatio < minAspectRatio) {
+        row.push(i);
+        return [true, false];
+    }
+    if (newAspectRatio > maxAspectRatio) {
+        if (row.length === 0) {
+            row.push(i);
+            return [true, true];
+        }
+        const previousRowWidthWithoutSpacing = width - (row.length - 1) * spacing;
+        const previousAspectRatio = newAspectRatio - aspects[i];
+        const previousTargetAspectRatio = previousRowWidthWithoutSpacing / target;
+        if (Math.abs(newAspectRatio - targetAspectRatio) > Math.abs(previousAspectRatio - previousTargetAspectRatio))
+            return [false, true];
+        row.push(i);
+        return [true, true];
+    }
+    row.push(i);
+    return [true, true];
+}
+const sumOf = (items, aspects) => {
+    let a = 0;
+    for (const j of items)
+        a += aspects[j];
+    return a;
+};
+/**
+ * Justified rows (Flickr / Google Photos style) of items with aspect ratios `aspects` (width / height; an item weight
+ * multiplies it), decided at container width `refWidth`; geometry in terms of the container width (the breakpoint's
+ * unit with one column).
+ */
+export function placeJustified(aspects, refWidth, options) {
+    return placeJustifiedRun(aspects, refWidth, options, null).geometry;
+}
+/**
+ * `placeJustified` with a checkpoint: when only items from index `from` on changed (same reference width + options),
+ * the rows closed before the one holding `from` (and before the previous last closed row, which the last-row
+ * treatment may rebalance) are kept with their geometry; the greedy pass restarts there. Equal to a full run.
+ */
+export function placeJustifiedRun(aspects, refWidth, options, resume) {
+    const count = aspects.length;
+    const target = Math.max(1, options.rowHeight);
+    const tolerance = options.tolerance ?? 0.25;
+    const minH = options.minRowHeight ?? 0.5 * target;
+    const maxH = options.maxRowHeight ?? 2 * target;
+    const [gapX, gapY] = options.gap;
+    const lastRow = options.lastRow ?? "fill";
+    const W = refWidth;
+    const clampAt = (k, A) => {
+        const h = (W - (k - 1) * gapX) / A;
+        const c = Math.max(minH, Math.min(h, maxH));
+        return c !== h ? c : null;
+    };
+    const rowHeightAt = (row) => row.clamped ?? (W - (row.items.length - 1) * gapX) / sumOf(row.items, aspects);
+    // computeLayout: rows at the reference width.
+    const rows = [];
+    // Checkpoint: kept closed rows end before `from - 1` (a row closes on the item after it, so a change at `from` can
+    // reopen the row ending at `from - 1`) and before the previous last closed row.
+    let keep = 0;
+    if (resume) {
+        const prevClosed = resume.run.closed;
+        const limit = Math.min(prevClosed.length - 1, resume.run.rows.length);
+        while (keep < limit && prevClosed[keep].items[prevClosed[keep].items.length - 1] + 1 < resume.from && prevClosed[keep] === resume.run.rows[keep])
+            keep++;
+        for (let r = 0; r < keep; r++)
+            rows.push(prevClosed[r]);
+    }
+    const start = keep ? rows[keep - 1].items[rows[keep - 1].items.length - 1] + 1 : 0;
+    let current = [];
+    const close = () => {
+        rows.push({ items: current, kind: "justify", style: "justify", clamped: clampAt(current.length, sumOf(current, aspects)) });
+        current = [];
+    };
+    for (let i = start; i < count; i++) {
+        const [added, complete] = addItem(current, aspects, i, W, gapX, target, tolerance);
+        if (complete) {
+            close();
+            if (!added) {
+                const [, again] = addItem(current, aspects, i, W, gapX, target, tolerance);
+                if (again)
+                    close();
+            }
+        }
+    }
+    const closed = rows.slice();
+    if (current.length) {
+        let filled = false;
+        if (lastRow === "fill") {
+            const prev = rows[rows.length - 1];
+            const pool = prev ? [...prev.items, ...current] : current;
+            // One row, or the best split into two, nearest to the target height (worst row of the two); only arrangements
+            // whose rows stay inside [minRowHeight, maxRowHeight] (a clamped row would crop: then the widow stays `left`).
+            const total = sumOf(pool, aspects);
+            const inRange = (h) => h >= minH - 1e-9 && h <= maxH + 1e-9;
+            const one = (W - (pool.length - 1) * gapX) / total;
+            let bestCost = inRange(one) ? Math.abs(one - target) : Infinity;
+            let split = pool.length;
+            let left = 0;
+            for (let m = 1; m < pool.length; m++) {
+                left += aspects[pool[m - 1]];
+                const h1 = (W - (m - 1) * gapX) / left;
+                const h2 = (W - (pool.length - m - 1) * gapX) / (total - left);
+                if (!inRange(h1) || !inRange(h2))
+                    continue;
+                const cost = Math.max(Math.abs(h1 - target), Math.abs(h2 - target));
+                if (cost < bestCost - 1e-9) {
+                    bestCost = cost;
+                    split = m;
+                }
+            }
+            if (bestCost < Infinity) {
+                if (prev)
+                    rows.pop();
+                for (const items of split === pool.length ? [pool] : [pool.slice(0, split), pool.slice(split)])
+                    rows.push({ items, kind: "justify", style: "justify", clamped: null });
+                filled = true;
+            }
+        }
+        if (!filled) {
+            // Widow at the previous row's height; one that would overflow the width at it becomes a justified row instead.
+            const style = lastRow === "fill" ? "left" : lastRow;
+            const prev = rows[rows.length - 1];
+            const widowH = prev ? rowHeightAt(prev) : Math.max(minH, Math.min(target, maxH));
+            const natural = sumOf(current, aspects) * widowH + (current.length - 1) * gapX;
+            if (natural > W + 1e-6)
+                rows.push({ items: current, kind: "justify", style: "justify", clamped: clampAt(current.length, sumOf(current, aspects)) });
+            else
+                rows.push({ items: current, kind: "widow", style, clamped: null });
+        }
+    }
+    // Geometry: linear in W. Kept rows (still final and unchanged) copy their item geometry.
+    const g = emptyGeometry(count);
+    const rowTop = new Float64Array(rows.length * 2);
+    const rowHeight = new Float64Array(rows.length * 2);
+    let first = 0;
+    if (resume) {
+        const prev = resume.run;
+        while (first < keep && rows[first] === prev.rows[first])
+            first++;
+        if (first) {
+            const end = rows[first - 1].items[rows[first - 1].items.length - 1] + 1;
+            const pg = prev.geometry;
+            g.x.set(pg.x.subarray(0, 2 * end));
+            g.width.set(pg.width.subarray(0, 2 * end));
+            g.height.set(pg.height.subarray(0, 2 * end));
+            g.top.set(pg.top.subarray(0, 2 * end));
+            g.ratio.set(pg.ratio.subarray(0, end));
+            rowTop.set(prev.rowTop.subarray(0, 2 * first));
+            rowHeight.set(prev.rowHeight.subarray(0, 2 * first));
+        }
+    }
+    let topK = 0;
+    let topC = 0;
+    let prevH = [0, target];
+    if (first) {
+        const r = first - 1;
+        prevH = [rowHeight[2 * r], rowHeight[2 * r + 1]];
+        topK = rowTop[2 * r] + prevH[0];
+        topC = rowTop[2 * r + 1] + prevH[1] + gapY;
+    }
+    for (let r = first; r < rows.length; r++) {
+        const row = rows[r];
+        const k = row.items.length;
+        const A = sumOf(row.items, aspects);
+        // Row height h = hk·W + hc; item widths a·(natural height) (+ the widow `justify` error share).
+        let hk;
+        let hc;
+        let nk;
+        let nc;
+        if (row.kind === "justify") {
+            nk = 1 / A;
+            nc = (-(k - 1) * gapX) / A;
+            if (row.clamped != null)
+                [hk, hc] = [0, row.clamped];
+            else
+                [hk, hc] = [nk, nc];
+        }
+        else {
+            // Widow at the previous row's height (upstream forceComplete(false, previous.height) / target height).
+            [hk, hc] = r > 0 ? prevH : [0, Math.max(minH, Math.min(target, maxH))];
+            [nk, nc] = [hk, hc];
+        }
+        // Width error per item for `justify` widows: (Σw + (k − 1)·gap − W) / k.
+        const ek = row.kind === "widow" && row.style === "justify" ? (A * nk - 1) / k : 0;
+        const ec = row.kind === "widow" && row.style === "justify" ? (A * nc + (k - 1) * gapX) / k : 0;
+        // Centered widows: offset (W − (Σw + (k − 1)·gap)) / 2 (upstream adds its container padding to the same centre).
+        const ok = row.kind === "widow" && row.style === "center" ? (1 - A * nk) / 2 : 0;
+        const oc = row.kind === "widow" && row.style === "center" ? (-(A * nc) - (k - 1) * gapX) / 2 : 0;
+        let xk = ok;
+        let xc = oc;
+        for (let j = 0; j < k; j++) {
+            const i = row.items[j];
+            const a = aspects[i];
+            const wk = a * nk - ek;
+            const wc = a * nc - ec;
+            g.x[2 * i] = xk;
+            g.x[2 * i + 1] = xc;
+            g.width[2 * i] = wk;
+            g.width[2 * i + 1] = wc;
+            g.height[2 * i] = hk;
+            g.height[2 * i + 1] = hc;
+            g.top[2 * i] = topK;
+            g.top[2 * i + 1] = topC;
+            // Height = width / aspect exactly when the row is neither clamped nor a justified widow.
+            g.ratio[i] = (row.kind === "justify" && row.clamped == null) || (row.kind === "widow" && row.style !== "justify") ? a : 0;
+            xk += wk;
+            xc += wc + gapX;
+        }
+        rowTop[2 * r] = topK;
+        rowTop[2 * r + 1] = topC;
+        rowHeight[2 * r] = hk;
+        rowHeight[2 * r + 1] = hc;
+        prevH = [hk, hc];
+        topK += hk;
+        topC += hc + (r < rows.length - 1 ? gapY : 0);
+    }
+    if (first && first === rows.length)
+        topC -= gapY;
+    g.extent = rows.length ? Float64Array.of(topK, topC) : new Float64Array(0);
+    return { geometry: g, closed, rows, rowTop, rowHeight };
+}

package/masonry/layout.d.ts

@@ -0,0 +1,200 @@
+import { type Geometry, type Rect } from "./geometry.js";
+export type Key = string | number;
+export type { Geometry, Rect } from "./geometry.js";
+/** Column count: a number, or a container-width breakpoint map (`{ 0: 2, 640: 3, 1024: 4 }`, min width → columns). */
+export type Columns = number | Readonly<Record<number, number>>;
+/** A per-item value that may differ per breakpoint (`2`, or `{ 0: 1, 768: 2 }`: min container width → value). */
+export type Responsive<T> = T | Readonly<Record<number, T>>;
+export interface Breakpoint {
+    /** Minimum container content width in px (the first is 0). */
+    min: number;
+    /** Column count from `min` on (justified rows: 1, the unit is the container width). */
+    columns: number;
+    /** `[column, row]` gaps in px from `min` on. */
+    gap: [number, number];
+}
+/** A gap: one value or `[column, row]` px. */
+export type Gap = number | readonly [number, number];
+/** Default columns: 2 below 640 px, 3 below 1024 px, 4 above (container width). */
+export declare const DEFAULT_COLUMNS: Readonly<Record<number, number>>;
+/** `gap` value → `[column, row]` px (default 16). */
+export declare function gapPair(gap: Gap | null | undefined): [number, number];
+/** The gap at breakpoint `min` of a `gap` prop (a value, or a container-width map of values). */
+export declare function gapAt(gap: Responsive<Gap> | null | undefined, min: number): [number, number];
+/** Map keys (container widths) of a responsive prop. */
+export declare const responsiveMins: (value: unknown) => number[];
+/**
+ * Extra container-width breakpoints of justified rows: inside a breakpoint every row scales with the width, so the
+ * ranges are geometric with `hi / lo ≤ (1 + tolerance) / (1 − tolerance)` (from 320 px; 0.25 → 533, 889, 1481, 2469):
+ * a row decided at the middle of its range stays within the height tolerance anywhere in it. Up to `maxWidth` (the
+ * grid never gets wider; fewer breakpoints = fewer CSS terms), else up to 4000 px.
+ */
+export declare function justifiedSplits(tolerance?: number, maxWidth?: number | null): number[];
+/** Breakpoints below `maxWidth` only (the grid is never wider): at least the first. */
+export declare function capBreakpoints(breakpoints: readonly Breakpoint[], maxWidth: number): Breakpoint[];
+/**
+ * Sorted breakpoints from `columns` (default `DEFAULT_COLUMNS`) or from `minItemWidth` (n·m + (n−1)·gap ≤ width), with
+ * the gap of each (`gap` may be a container-width map; its keys split breakpoints too, as do `splits`).
+ */
+export declare function resolveBreakpoints(columns?: Columns | null, minItemWidth?: number | null, maxColumns?: number, gap?: Responsive<Gap> | null, splits?: readonly number[]): Breakpoint[];
+/**
+ * `sizes` attribute for a masonry image (`?image` srcset): the column width per breakpoint. Breakpoints are container
+ * widths; `sizes` media queries are viewport widths, so the container is described relative to the viewport:
+ * container = `min(100vw − inset, maxWidth)` (`inset`: px of the viewport outside the grid — page padding, a sidebar;
+ * `maxWidth`: the grid's `maxWidth`). A breakpoint at container width `min` then starts at viewport `min + inset`;
+ * from viewport `maxWidth + inset` on, every width is a constant. `span` = columns the image covers (number or
+ * container-width map, e.g. a live span's current value).
+ */
+export declare function masonrySizes(options?: {
+    columns?: Columns | null;
+    minItemWidth?: number | null;
+    maxColumns?: number;
+    gap?: Responsive<Gap> | null;
+    span?: Responsive<number> | null;
+    inset?: number;
+    maxWidth?: number | null;
+}): string;
+/** Index of the breakpoint active at container width `width`. */
+export declare function breakpointAt(breakpoints: readonly Breakpoint[], width: number): number;
+/** A per-item responsive value at breakpoint `min` (the largest map key ≤ `min`; a plain value everywhere). */
+export declare function responsiveAt<T>(value: Responsive<T> | null | undefined, min: number, fallback: T): T;
+/** Column width at container width `width`. */
+export declare const columnWidth: (width: number, columns: number, gapX: number) => number;
+/**
+ * Deterministic container width the greedy compares columns at, per breakpoint: the middle of its range (from
+ * max(min, 320) to the next breakpoint, or +25 % for the last). `override` replaces it for every breakpoint.
+ */
+export declare function referenceWidths(breakpoints: readonly Breakpoint[], override?: number | null, maxWidth?: number | null): number[];
+/** Placement of `count` items in `columns` columns: item i is in column `col[i]` at `top = a[i]·w + b[i]` px. */
+export interface MasonryPlacement {
+    columns: number;
+    col: Uint16Array;
+    a: Float64Array;
+    b: Float64Array;
+    /** Per column: Σα and Σ(β + gapY) of its items (height = colA·w + colB − gapY when non-empty). */
+    colA: Float64Array;
+    colB: Float64Array;
+    colCount: Uint32Array;
+}
+/**
+ * Shortest-column greedy. Item i is `alpha[i]·w + beta[i]` px tall (exact: α = 1 / aspect ratio, β = extra px;
+ * measured: α = 0, β = height). Columns compare at column width `refW` (ties → the lowest column).
+ */
+export declare function placeMasonry(alpha: ArrayLike<number>, beta: ArrayLike<number>, columns: number, refW: number, gapY: number): MasonryPlacement;
+/** Items of a columns placement: height `alpha·width + beta` px (width = the item's span width), column span. */
+export interface ColumnsInput {
+    alpha: ArrayLike<number>;
+    beta: ArrayLike<number>;
+    /** Columns each item spans (default 1; clamped to the column count). */
+    span?: ArrayLike<number> | null;
+}
+/** Column state: per column the terms of its bottom (+ the row gap: the top of its next item). */
+interface ColumnsState {
+    bottoms: number[][];
+    count: Uint32Array;
+    last: Int32Array;
+}
+/** A columns placement (one breakpoint) and what an incremental re-place needs. */
+export interface ColumnsRun {
+    geometry: Geometry;
+    /** First column of item i, and its span. */
+    col: Uint16Array;
+    span: Uint16Array;
+    columns: number;
+    /** State before item `j · CHECKPOINT` (incremental re-place resumes from the nearest one). */
+    checkpoints: ColumnsState[];
+    /** Final state. */
+    state: ColumnsState;
+}
+/** Items between incremental checkpoints. */
+export declare const CHECKPOINT = 32;
+/**
+ * Shortest-column greedy with column spans, in linear terms of the column width `u` (see `./geometry.ts`). Columns
+ * compare at `refW` (ties → the leftmost); an item spanning s columns goes where the highest of its s columns is the
+ * lowest, its top is the max of their bottoms (term set, pruned over `u ∈ [lo, hi]`), so it never overlaps at any
+ * width of the range. One-column items keep one term (the PR-1 `placeMasonry` picture). `resume` re-places from item
+ * `from` on (same columns / widths / gaps; the result equals a full placement: `masonry-layout.test.ts`).
+ */
+export declare function placeColumns(input: ColumnsInput, columns: number, refW: number, lo: number, hi: number, gapX: number, gapY: number, resume?: {
+    run: ColumnsRun;
+    from: number;
+} | null): ColumnsRun;
+/**
+ * `fit="both"`: stretch the last item of every column down to the content bottom (the tallest column), so the grid
+ * ends flush; images inside fill with `object-fit: cover`. Items whose top is a term set (under a spanning item) or
+ * that span columns keep their height. Returns a new geometry (the run's stays reusable for incremental re-places).
+ */
+export declare function fitColumns(run: ColumnsRun, lo: number, hi: number): Geometry;
+/**
+ * Numeric shortest-column greedy with spans at one column width `w` (measured items, virtualized layout): item i is
+ * `heights[i]` px tall and spans `spans[i]` columns; columns start at `initial` (px tops of the next item per column,
+ * e.g. under a server-placed prefix). Returns start-edge x, top y, width per item and the content height.
+ */
+export declare function placeNumeric(heights: ArrayLike<number>, spans: ArrayLike<number> | null, columns: number, w: number, gapX: number, gapY: number, initial?: ArrayLike<number> | null): {
+    x: Float64Array;
+    y: Float64Array;
+    width: Float64Array;
+    height: number;
+    bottoms: Float64Array;
+};
+/** Column-width range `[lo, hi]` of breakpoint b (the last one: up to a 100 000 px container). */
+export declare function unitRange(breakpoints: readonly Breakpoint[], b: number, maxWidth?: number | null): [number, number];
+/** Content height of a placement at column width `w`. */
+export declare function masonryHeight(p: MasonryPlacement, w: number, gapY: number): number;
+/** Pixel rects (LTR, x from the start edge) of a placement at container width `width`. */
+export declare function masonryRects(p: MasonryPlacement, alpha: ArrayLike<number>, beta: ArrayLike<number>, width: number, gapX: number): Rect[];
+export type BentoPack = "dense" | "skyline";
+/** Cell placement of `count` tiles (0-based row / column, spans clamped to the column count). */
+export interface BentoPlacement {
+    columns: number;
+    row: Uint32Array;
+    col: Uint16Array;
+    rowSpan: Uint16Array;
+    colSpan: Uint16Array;
+    /** Rows used. */
+    rows: number;
+}
+/** Packs tiles of `colSpans[i]` × `rowSpans[i]` cells into `columns` columns. */
+export declare function packBento(colSpans: ArrayLike<number>, rowSpans: ArrayLike<number>, columns: number, pack?: BentoPack): BentoPlacement;
+/**
+ * Custom properties of the grid element: `--rv-w<b>` (column width of breakpoint b; masked to ≈ −1e9 px outside its
+ * range when there are several), `--rv-m<b>` (the mask alone: 0 inside, ≈ 1e9 px outside), `--rv-mw` (the active
+ * column width). `100cqw` resolves against the root (an `inline-size` container) wherever the variables are used.
+ */
+/**
+ * Registers the grid custom properties as inherited `<length>`s (client, once per name): the grid then computes each
+ * masked width once and items inherit a plain length, instead of re-parsing the clamp() token stream per item (~3×
+ * faster style recalc for 1k items, measured). Layout is identical without it; `@rivetjs/cdk/masonry.css` declares the
+ * same names with `@property` for server-rendered pages before any script runs. No-op on the server.
+ */
+export declare function registerGridProperties(count: number): void;
+export declare function gridVars(breakpoints: readonly Breakpoint[]): Record<string, string>;
+/** The active column gap as CSS (a px value, or `var(--rv-gx)` when it differs per breakpoint). */
+export declare const columnGapCss: (breakpoints: readonly Breakpoint[]) => string;
+/** Bento row height: px, or `w / aspectRatio`. */
+export type BentoRowHeight = number | {
+    aspectRatio: number;
+} | "auto";
+/** Geometry of a bento placement (unit = the column width; `rowHeight` px or `{ aspectRatio }` of the column width). */
+export declare function bentoGeometry(p: BentoPlacement, rowHeight: number | {
+    aspectRatio: number;
+}, gapX: number, gapY: number): Geometry;
+/** Bento pixel rects at container width `width` (for keyboard geometry / tests). */
+export declare function bentoRects(p: BentoPlacement, rowHeight: number | {
+    aspectRatio: number;
+}, width: number, gapX: number, gapY: number): Rect[];
+/** Aspect ratio (width / height) from an item's `aspectRatio`, else `width / height`; `null` when unknown. */
+export declare function defaultAspectRatio(item: unknown): number | null;
+/** Fixed px height of an item without a ratio: `item.height` when it has neither `width` nor `aspectRatio`. */
+export declare function defaultItemHeight(item: unknown): number | null;
+/** Column span (justified: width weight) from an item's `span`. */
+export declare const defaultSpan: (item: unknown) => Responsive<number>;
+/** A usable ratio (finite, > 0) or null. */
+export declare const validRatio: (r: unknown) => number | null;
+/** Item key: `id`, else `key`, else the index. */
+export declare function defaultItemKey(item: unknown, index: number): Key;
+/** Column / row spans from an item's `colSpan` / `rowSpan`. */
+export declare const defaultColSpan: (item: unknown) => Responsive<number>;
+export declare const defaultRowSpan: (item: unknown) => Responsive<number>;
+/** `gap` prop → `[column, row]` px at the smallest breakpoint. */
+export declare const gapOf: (gap: Responsive<Gap> | null | undefined) => [number, number];