Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
/**
* Per-parent masonry pack layout. Pure, browser-free and unit-testable.
*
* The backend ships a containment tree and no placement. Every card is sized by
* importance (more central = bigger, within bounds so nothing is unreadably
* small) and the cards are row-packed into centred, variable-width rows. The
* staggered row edges and the size variation give an organic architecture-map
* feel rather than a rigid grid, while the whole cluster is uniform-fit
* (aspect-preserving) into the parent so cards keep a single landscape shape.
* The rect emitted is in parent `[0,1]` space, which is what the clip-and-scale
* composition in `geometry.ts` consumes.
*/
import type { Rect } from "./camera";
import {
CARD_ASPECT,
PACK_GUTTER,
PACK_IMPORTANCE_GAMMA,
PACK_SIZE_MAX,
PACK_SIZE_MIN,
} from "./constants";
/** The minimal slice of a node the layout needs (placement order + sizing). */
export interface LayoutChild {
id: string;
sibling_rank: number;
importance: number;
}
export interface PackLayoutOptions {
/** Whitespace between cards, in the same relative units as the card sides. */
gutter?: number;
/** Card height for the least-important sibling. */
sizeMin?: number;
/** Card height for the most-important sibling. */
sizeMax?: number;
/** Importance curve; <1 lifts small cards so minor nodes stay readable. */
gamma?: number;
/** Card width : height. */
aspect?: number;
}
/**
* Choose a target column count whose column/row ratio tracks the parent's world
* aspect, so the packed cluster's bounding box roughly matches the parent shape
* and fits with little margin. Returns the tightened dimensions (no empty
* trailing column). Shared with the pack (which packs to ~`cols` cards per row).
*/
export function gridDimensions(
count: number,
parentAspect: number,
): { cols: number; rows: number } {
if (count <= 0) return { cols: 0, rows: 0 };
if (count === 1) return { cols: 1, rows: 1 };
const aspect = Math.min(6, Math.max(1 / 6, parentAspect || 1));
let cols = Math.round(Math.sqrt(count * aspect));
cols = Math.min(count, Math.max(1, cols));
const rows = Math.ceil(count / cols);
// Re-derive columns from the row count so the grid is as tight as possible for
// that many rows (this can narrow the column count, which is intended).
return { cols: Math.ceil(count / rows), rows };
}
interface Packed {
id: string;
w: number;
h: number;
}
/**
* Lay `children` out as an importance-weighted masonry pack inside the unit
* parent box. Children are ordered by `sibling_rank` (most important first, so
* the biggest cards read top-left), sized by importance normalised across the
* sibling set, then greedily row-packed to ~`cols` cards per row. Rows are
* centred (so left edges stagger) and each card is centred in its row band (so
* top edges stagger); the whole cluster is uniform-fit into `[0,1]²`. Returns
* each child's rect in parent `[0,1]` space. Deterministic: stable order, ties
* broken by id; no randomness.
*/
export function packLayout(
children: readonly LayoutChild[],
parentAspect: number,
opts: PackLayoutOptions = {},
): Map<string, Rect> {
const gutter = opts.gutter ?? PACK_GUTTER;
const sizeMin = opts.sizeMin ?? PACK_SIZE_MIN;
const sizeMax = opts.sizeMax ?? PACK_SIZE_MAX;
const gamma = opts.gamma ?? PACK_IMPORTANCE_GAMMA;
const baseAspect = opts.aspect ?? CARD_ASPECT;
// Cards are sized in the parent's LOCAL [0,1] box, but `composeRect` later
// stretches that box by the parent's own world width and height separately.
// Since a parent card is itself landscape, sizing to `baseAspect` directly
// would let every nesting level re-multiply the horizontal stretch, so a few
// levels deep a card collapses into an unreadable sliver. Pre-divide by the
// parent aspect: once `composeRect` re-applies it, each card lands at
// `baseAspect` on screen at any depth. Clamp so an extreme parent shape can't
// invert or explode the local card.
const aspect = Math.min(8, Math.max(0.2, baseAspect / (parentAspect || 1)));
const out = new Map<string, Rect>();
const n = children.length;
if (n === 0) return out;
const ordered = [...children].sort(
(a, b) => a.sibling_rank - b.sibling_rank || (a.id < b.id ? -1 : 1),
);
// Normalise importance across this sibling set so each parent shows a full
// range of sizes (min-max within the group). If they are all equal, everyone
// gets the max size (a uniform, generously-sized cluster).
let lo = Infinity;
let hi = -Infinity;
for (const c of ordered) {
const v = Number.isFinite(c.importance) ? c.importance : 0;
if (v < lo) lo = v;
if (v > hi) hi = v;
}
const span = hi - lo;
const heightOf = (c: LayoutChild): number => {
const v = Number.isFinite(c.importance) ? c.importance : 0;
const norm = span > 1e-9 ? (v - lo) / span : 1;
return sizeMin + (sizeMax - sizeMin) * Math.pow(norm, gamma);
};
const cards: Packed[] = ordered.map((c) => {
const h = heightOf(c);
return { id: c.id, w: h * aspect, h };
});
// Greedy row packing to a target width of ~`cols` average-width cards.
const { cols } = gridDimensions(n, parentAspect);
const avgW = cards.reduce((s, c) => s + c.w, 0) / n;
const targetRowW = cols * avgW + Math.max(0, cols - 1) * gutter;
const rows: Packed[][] = [];
let cur: Packed[] = [];
let curW = 0;
for (const card of cards) {
const add = (cur.length > 0 ? gutter : 0) + card.w;
if (cur.length > 0 && curW + add > targetRowW) {
rows.push(cur);
cur = [];
curW = 0;
}
curW += (cur.length > 0 ? gutter : 0) + card.w;
cur.push(card);
}
if (cur.length > 0) rows.push(cur);
const rowW = (row: Packed[]): number =>
row.reduce((s, c) => s + c.w, 0) + Math.max(0, row.length - 1) * gutter;
const rowH = (row: Packed[]): number => row.reduce((m, c) => Math.max(m, c.h), 0);
const maxRowW = Math.max(...rows.map(rowW));
const totalH = rows.reduce((s, r) => s + rowH(r), 0) + Math.max(0, rows.length - 1) * gutter;
// Uniform (aspect-preserving) fit of the packed cluster into the unit box,
// centred, so cards keep one shape and nothing spills outside the parent.
const scale = Math.min(1 / maxRowW, 1 / totalH);
const offX = (1 - maxRowW * scale) / 2;
const offY = (1 - totalH * scale) / 2;
let y = 0;
for (const row of rows) {
const h = rowH(row);
let x = (maxRowW - rowW(row)) / 2; // centre the row -> staggered left edges
for (const card of row) {
const cy = y + (h - card.h) / 2; // centre in the band -> staggered top edges
out.set(card.id, {
x: offX + x * scale,
y: offY + cy * scale,
w: card.w * scale,
h: card.h * scale,
});
x += card.w + gutter;
}
y += h + gutter;
}
return out;
}