@multiplatform.one/theme 7.3.0 → 7.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/theme",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "description": "Tamagui theme system for multiplatform.one",
   "keywords": [
     "multiplatform",
@@ -53,8 +53,8 @@
     "@tamagui/toast": "2.7.6",
     "@tamagui/web": "2.7.6",
     "react-cookie": "^8.1.2",
-    "@multiplatform.one/platform": "7.3.0",
-    "@multiplatform.one/store": "7.3.0"
+    "@multiplatform.one/platform": "7.4.0",
+    "@multiplatform.one/store": "7.4.0"
   },
   "devDependencies": {
     "@tamagui/animations-css": "2.7.6",
@@ -69,8 +69,8 @@
     "tamagui": "2.7.6",
     "typescript": "~5.9.3",
     "vitest": "^4.1.5",
-    "@multiplatform.one/config": "7.3.0",
-    "@multiplatform.one/test-utils": "7.3.0"
+    "@multiplatform.one/config": "7.4.0",
+    "@multiplatform.one/test-utils": "7.4.0"
   },
   "peerDependencies": {
     "@tamagui/animations-css": "^2.0.0-rc",

package/src/theme/index.ts

@@ -26,6 +26,7 @@ export * from "./resolveKnobs";
 export * from "./shared";
 export * from "./sizeRecipes";
 export * from "./Surface";
+export * from "./tileSizes";
 
 export * from "./theme";
 export * from "./Tint";

package/src/theme/recipeInputs.ts

@@ -16,6 +16,14 @@
  * `baseHeight * stepRatio ** step`.
  */
 
+import {
+  cloneTileSizeInputs,
+  generateTileSizeLadder,
+  resolveTileSizeInputs,
+  type TileSizeInputs,
+  type TileSizeLadder,
+} from "./tileSizes";
+
 export const SIZE_RECIPE_TOKENS = [
   "$1",
   "$1.5",
@@ -57,6 +65,11 @@ export type SizeRecipeInputs = {
   compactRatios: SizeRecipeRatios;
   radiusPx: number;
   touchFloor: number;
+  /**
+   * Tile-size ladder inputs (MPO-31). Merged over `defaultTileSizeInputs`;
+   * the ladder table derives from these the way every other table does.
+   */
+  tile?: Partial<TileSizeInputs>;
 };
 
 /** @deprecated Use `SizeRecipeInputs`. */
@@ -106,6 +119,8 @@ export type GeneratedSizeRecipes = {
   typeVariants: Record<string, SizeRecipeTypeVariant>;
   iconVariants: Record<string, SizeRecipeIconVariant>;
   families: RecipeFamilies;
+  /** Tile-size ladder (MPO-31) — derived from `inputs.tile` over the measured defaults. */
+  tiles: TileSizeLadder;
 };
 
 export const SIZE_TOKEN_EXPONENTS: Record<SizeRecipeToken, number> = {
@@ -205,6 +220,7 @@ export function cloneSizeRecipeInputs(inputs: SizeRecipeInputs): SizeRecipeInput
     sizeFactors: inputs.sizeFactors ? { ...inputs.sizeFactors } : undefined,
     ratios: { ...inputs.ratios },
     compactRatios: { ...inputs.compactRatios },
+    tile: inputs.tile ? cloneTileSizeInputs(inputs.tile) : undefined,
   };
 }
 
@@ -228,6 +244,10 @@ export function resolveSizeRecipeInputs(partial: Partial<SizeRecipeInputs> = {})
     touchFloor: partial.touchFloor ?? DEFAULT_SIZE_RECIPE_INPUTS.touchFloor,
   };
 
+  if (partial.tile !== undefined) {
+    resolved.tile = partial.tile ? resolveTileSizeInputs(partial.tile) : undefined;
+  }
+
   if (hasTokenHeights) {
     resolved.tokenHeights = partial.tokenHeights ? { ...partial.tokenHeights } : undefined;
     if (hasSizeFactors) {
@@ -383,5 +403,6 @@ export function generateSizeRecipes(partial: Partial<SizeRecipeInputs> = {}): Ge
     typeVariants: control.typeVariants,
     iconVariants: control.iconVariants,
     families,
+    tiles: generateTileSizeLadder(resolveTileSizeInputs(inputs.tile ?? {})),
   };
 }

package/src/theme/sizeRecipes.ts

@@ -111,11 +111,27 @@ export const SIZE_RECIPE_COMPACT_RATIOS = recipeFamilies.controlCompact.ratios;
 
 export const SIZE_RECIPE_FAMILY_NAMES = ["control", "controlCompact"] as const;
 
+/**
+ * Live tile-size ladder (MPO-31) — generated from `inputs.tile` over the
+ * measured defaults, adopted in place on `setSizeRecipeInputs` like every
+ * other live table. Never handwrite rungs; restyle through inputs.
+ */
+export const tileSizeLadder = initial.tiles;
+
+export function getTileSizeLadder(): typeof tileSizeLadder {
+  return tileSizeLadder;
+}
+
 function adoptGenerated(next: GeneratedSizeRecipes): GeneratedSizeRecipes {
   adoptFamily(recipeFamilies.control, next.families.control);
   adoptFamily(recipeFamilies.controlCompact, next.families.controlCompact);
+  replaceRecord(
+    tileSizeLadder as unknown as Record<string, unknown>,
+    next.tiles as unknown as Record<string, unknown>,
+  );
   current = {
     ...next,
+    tiles: tileSizeLadder,
     heights: SIZE_RECIPE_HEIGHTS,
     heightsTouch: SIZE_RECIPE_HEIGHTS_TOUCH,
     recipes: sizeRecipes,

package/src/theme/tileSizes.spec.ts

@@ -0,0 +1,139 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { generateSizeRecipes } from "./recipeInputs";
+import { getSizeRecipeInputs, setSizeRecipeInputs, tileSizeLadder } from "./sizeRecipes";
+import {
+  defaultTileSizeInputs,
+  generateTileSizeLadder,
+  mediaAspectRatios,
+  resolveMediaAspect,
+  resolveTileSizeInputs,
+  tileColumnsForWidth,
+  tileRungFlexProps,
+  tileSizeRungs,
+} from "./tileSizes";
+
+afterEach(() => {
+  setSizeRecipeInputs();
+});
+
+describe("tile-size ladder (MPO-31 H1)", () => {
+  it("defaults to the measured consumer ladders, not invented numbers", () => {
+    const ladder = generateTileSizeLadder(resolveTileSizeInputs());
+    // sm..xl are Lookout's TILE_SIZES basis/max (identical to the SPA's
+    // TILE_MIN); xs is the launcher icon-plate minmax(104px,1fr) track.
+    expect(ladder.sm).toEqual({ minWidth: 220, maxWidth: 300 });
+    expect(ladder.md).toEqual({ minWidth: 320, maxWidth: 440 });
+    expect(ladder.lg).toEqual({ minWidth: 480, maxWidth: 720 });
+    expect(ladder.xl).toEqual({ minWidth: 720, maxWidth: 1400 });
+    expect(ladder.xs.minWidth).toBe(104);
+    // xs has no measured max; it derives from maxRatio (440/320).
+    expect(ladder.xs.maxWidth).toBe(Math.round(104 * defaultTileSizeInputs.maxRatio));
+  });
+
+  it("is a generated table: rungs are monotonic and max >= min on every rung", () => {
+    const ladder = generateTileSizeLadder(resolveTileSizeInputs());
+    for (let i = 0; i < tileSizeRungs.length; i++) {
+      const stop = ladder[tileSizeRungs[i]];
+      expect(stop.maxWidth).toBeGreaterThanOrEqual(stop.minWidth);
+      if (i > 0) {
+        expect(stop.minWidth).toBeGreaterThan(ladder[tileSizeRungs[i - 1]].minWidth);
+      }
+    }
+  });
+
+  it("a bare baseWidth override regenerates the whole ladder geometrically", () => {
+    const inputs = resolveTileSizeInputs({ baseWidth: 280 });
+    // Scaling override drops the measured pins (the resolveSizeRecipeInputs contract).
+    expect(inputs.rungWidths).toBeUndefined();
+    expect(inputs.widthFactors).toBeUndefined();
+    expect(inputs.rungMaxWidths).toBeUndefined();
+    const ladder = generateTileSizeLadder(inputs);
+    expect(ladder.md.minWidth).toBe(280);
+    expect(ladder.lg.minWidth).toBe(Math.round(280 * 1.5));
+    expect(ladder.xl.minWidth).toBe(Math.round(280 * 1.5 ** 2));
+    expect(ladder.sm.minWidth).toBe(Math.round(280 / 1.5));
+    expect(ladder.xs.minWidth).toBe(Math.round(280 / 1.5 ** 2));
+    for (const rung of tileSizeRungs) {
+      expect(ladder[rung].maxWidth).toBe(
+        Math.round(ladder[rung].minWidth * defaultTileSizeInputs.maxRatio),
+      );
+    }
+  });
+
+  it("explicit rungMaxWidths pin maxes; maxRatio covers the rest", () => {
+    const ladder = generateTileSizeLadder(
+      resolveTileSizeInputs({ baseWidth: 300, maxRatio: 2, rungMaxWidths: { md: 555 } }),
+    );
+    expect(ladder.md).toEqual({ minWidth: 300, maxWidth: 555 });
+    expect(ladder.lg.maxWidth).toBe(ladder.lg.minWidth * 2);
+  });
+
+  it("tileRungFlexProps is the wrapping-flex tile fragment (the Lookout idiom)", () => {
+    const ladder = generateTileSizeLadder(resolveTileSizeInputs());
+    expect(tileRungFlexProps(ladder.md)).toEqual({
+      flexGrow: 1,
+      flexBasis: 320,
+      minWidth: 320,
+      maxWidth: 440,
+    });
+  });
+
+  it("tileColumnsForWidth derives fixed-column counts from the rung and the gutter", () => {
+    const ladder = generateTileSizeLadder(resolveTileSizeInputs());
+    // A 1024 window at md with a 12px gutter fits 3 columns.
+    expect(tileColumnsForWidth(1024, ladder.md, 12)).toBe(3);
+    // xs at the launcher's own 8px gutter reproduces the springboard split:
+    // 6 columns at the 700px wide-breakpoint, 4 in the phone band.
+    expect(tileColumnsForWidth(700, ladder.xs, 8)).toBe(6);
+    expect(tileColumnsForWidth(500, ladder.xs, 8)).toBe(4);
+    // Never fewer than one column.
+    expect(tileColumnsForWidth(80, ladder.md)).toBe(1);
+    expect(tileColumnsForWidth(0, ladder.md)).toBe(1);
+    expect(tileColumnsForWidth(Number.NaN, ladder.md)).toBe(1);
+  });
+
+  it("rides recipeInputs: generateSizeRecipes carries tiles and setSizeRecipeInputs rewrites the live ladder in place", () => {
+    expect(generateSizeRecipes().tiles.md).toEqual({ minWidth: 320, maxWidth: 440 });
+
+    const live = tileSizeLadder;
+    expect(live.md.minWidth).toBe(320);
+    setSizeRecipeInputs({ tile: { baseWidth: 280 } });
+    // Same object identity (styled()-spread safety), new generated rows.
+    expect(tileSizeLadder).toBe(live);
+    expect(tileSizeLadder.md.minWidth).toBe(280);
+    expect(tileSizeLadder.lg.minWidth).toBe(420);
+    // The stored inputs round-trip through getSizeRecipeInputs.
+    expect(getSizeRecipeInputs().tile?.baseWidth).toBe(280);
+
+    setSizeRecipeInputs();
+    expect(tileSizeLadder.md).toEqual({ minWidth: 320, maxWidth: 440 });
+    expect(tileSizeLadder.sm).toEqual({ minWidth: 220, maxWidth: 300 });
+  });
+});
+
+describe("media aspect vocabulary (MPO-31 H2)", () => {
+  it("names resolve to their measured ratios", () => {
+    expect(resolveMediaAspect("square")).toBe(1);
+    expect(resolveMediaAspect("photo")).toBeCloseTo(4 / 3);
+    // The Lookout frame shape — desktop screen captures at 16:10.
+    expect(resolveMediaAspect("screen")).toBeCloseTo(1.6);
+    expect(resolveMediaAspect("video")).toBeCloseTo(16 / 9);
+    expect(resolveMediaAspect("portrait")).toBeCloseTo(3 / 4);
+    expect(Object.keys(mediaAspectRatios)).toEqual([
+      "square",
+      "photo",
+      "screen",
+      "video",
+      "portrait",
+    ]);
+  });
+
+  it("numbers pass through; nullish and junk fall back to square", () => {
+    expect(resolveMediaAspect(1.6)).toBe(1.6);
+    expect(resolveMediaAspect()).toBe(1);
+    expect(resolveMediaAspect(null)).toBe(1);
+    expect(resolveMediaAspect(0)).toBe(1);
+    expect(resolveMediaAspect(-2)).toBe(1);
+    expect(resolveMediaAspect(Number.POSITIVE_INFINITY)).toBe(1);
+  });
+});

package/src/theme/tileSizes.ts

@@ -0,0 +1,291 @@
+/**
+ * Tile-size ladder + media-aspect vocabulary (MPO-31, design-system/12 D.3
+ * holes H1/H2).
+ *
+ * Every tile wall needs the same two decisions: HOW BIG is a tile (a small
+ * named ladder a person can pick from — the user-facing S/M/L/XL control)
+ * and WHAT SHAPE is its media (so the loading skeleton is the same shape as
+ * the image that replaces it). Before this module both were app-invented:
+ * the console's `launcherGeometry.ts` (03-our-surfaces.md DL-9) and
+ * Lookout's private `TILE_SIZES` were the same gap twice.
+ *
+ * Like the control-size recipes (LC-70 RECIPE-INPUTS), STORED INPUTS are the
+ * source of truth and the ladder table is DERIVED — never handwritten at a
+ * call site. The default rung values are the MEASURED ladders from the two
+ * real consumers, not invented numbers:
+ *
+ * | rung | minWidth | maxWidth | measured from                                  |
+ * |------|----------|----------|------------------------------------------------|
+ * | xs   | 104      | 143      | launcher icon-plate track `minmax(104px,1fr)`  |
+ * | sm   | 220      | 300      | Lookout `TILE_SIZES.s` / SPA `TILE_MIN.s`      |
+ * | md   | 320      | 440      | Lookout `TILE_SIZES.m` / SPA `TILE_MIN.m`      |
+ * | lg   | 480      | 720      | Lookout `TILE_SIZES.l` / SPA `TILE_MIN.l`      |
+ * | xl   | 720      | 1400     | Lookout `TILE_SIZES.xl` / SPA `TILE_MIN.xl`    |
+ *
+ * `{ baseWidth: 280 }` (no rungWidths / widthFactors) regenerates the whole
+ * ladder geometrically from `baseWidth * stepRatio ** step`, the same
+ * override contract `resolveSizeRecipeInputs` gives `baseHeight`.
+ *
+ * OWNERSHIP (12-one-design.md Part B): the RUNGS are universal — generated
+ * here, restyled only through recipe inputs
+ * (`setSizeRecipeInputs({ tile })` / `createDefaultThemeConfig({ recipeInputs:
+ * { tile } })`). WHICH rung a surface shows is per-app (a prop, often
+ * persisted per user). Tile gutters stay on the space knob and tile rounding
+ * on the borderRadius knob — this module never emits a gap or a radius.
+ *
+ * DENSITY (LC-76): density moves SPACE only. A compact density steps the
+ * gutters between tiles (via the space knob) and must never re-rung the
+ * ladder — tile magnitude is content scale, not chrome scale, so nothing
+ * here reads the density knob.
+ */
+
+// ── Rungs ─────────────────────────────────────────────────────
+
+export const tileSizeRungs = ["xs", "sm", "md", "lg", "xl"] as const;
+
+export type TileSizeRung = (typeof tileSizeRungs)[number];
+
+/** One rung: the narrowest a tile may render, and the widest. */
+export type TileSizeStop = {
+  minWidth: number;
+  maxWidth: number;
+};
+
+export type TileSizeLadder = Record<TileSizeRung, TileSizeStop>;
+
+// ── Inputs ────────────────────────────────────────────────────
+
+export type TileSizeInputs = {
+  /** Desktop px min-width of the `md` rung. */
+  baseWidth: number;
+  /** Rung-to-rung ratio when regenerating geometrically. */
+  stepRatio: number;
+  /** Exponent of each rung relative to `md` (0). */
+  rungSteps: Record<TileSizeRung, number>;
+  /**
+   * Absolute desktop px min-widths. When omitted, min-widths come from
+   * `baseWidth * stepRatio ** step` (or `widthFactors`).
+   */
+  rungWidths?: Partial<Record<TileSizeRung, number>>;
+  /**
+   * Optional per-rung scale relative to `baseWidth`. Used only when
+   * `rungWidths` is omitted. Factors are `stepRatio ** exponent` otherwise.
+   */
+  widthFactors?: Partial<Record<TileSizeRung, number>>;
+  /** maxWidth = minWidth * maxRatio for any rung `rungMaxWidths` does not pin. */
+  maxRatio: number;
+  /** Absolute desktop px max-widths (measured pins win over `maxRatio`). */
+  rungMaxWidths?: Partial<Record<TileSizeRung, number>>;
+};
+
+export const tileSizeStepExponents: Record<TileSizeRung, number> = {
+  xs: -2,
+  sm: -1,
+  md: 0,
+  lg: 1,
+  xl: 2,
+};
+
+// Measured min-widths: xs is the launcher/springboard icon-plate grid track
+// (`minmax(104px,1fr)` — launcherGeometry.ts / traefik menu.go); sm..xl are
+// Lookout's `TILE_SIZES` basis values, identical in the production SPA's
+// `TILE_MIN` map. Kept explicit so adopting the ladder is a rendered no-op
+// for both consumers.
+const measuredRungWidths: Record<TileSizeRung, number> = {
+  xs: 104,
+  sm: 220,
+  md: 320,
+  lg: 480,
+  xl: 720,
+};
+
+/** Lossless relative table: the measured 104/220/320/480/720 ramp at baseWidth 320. */
+export const defaultWidthFactors: Record<TileSizeRung, number> = {
+  xs: 104 / 320,
+  sm: 220 / 320,
+  md: 1,
+  lg: 480 / 320,
+  xl: 720 / 320,
+};
+
+// Measured max-widths (Lookout `TILE_SIZES` max). xl's 1.94x is the
+// deliberate "one huge tile" rung; xs has no measured max (the launcher caps
+// tiles by column count), so it derives from `maxRatio`.
+const measuredRungMaxWidths: Partial<Record<TileSizeRung, number>> = {
+  sm: 300,
+  md: 440,
+  lg: 720,
+  xl: 1400,
+};
+
+export const defaultTileSizeInputs: TileSizeInputs = {
+  baseWidth: 320,
+  stepRatio: 1.5,
+  rungSteps: { ...tileSizeStepExponents },
+  rungWidths: { ...measuredRungWidths },
+  widthFactors: { ...defaultWidthFactors },
+  // Lookout md: 440/320. The measured sm (1.36) and lg (1.5) bracket it.
+  maxRatio: 440 / 320,
+  rungMaxWidths: { ...measuredRungMaxWidths },
+};
+
+/**
+ * Deep copy that PRESERVES partiality: keys the caller never set stay
+ * unset, so a later `resolveTileSizeInputs` still sees them as defaults
+ * rather than explicit undefineds.
+ */
+export function cloneTileSizeInputs<T extends Partial<TileSizeInputs>>(inputs: T): T {
+  const clone = { ...inputs };
+  if (inputs.rungSteps) clone.rungSteps = { ...inputs.rungSteps };
+  if (inputs.rungWidths) clone.rungWidths = { ...inputs.rungWidths };
+  if (inputs.widthFactors) clone.widthFactors = { ...inputs.widthFactors };
+  if (inputs.rungMaxWidths) clone.rungMaxWidths = { ...inputs.rungMaxWidths };
+  return clone;
+}
+
+/**
+ * Fill defaults. `{ baseWidth: 280 }` (any scaling override without explicit
+ * tables) drops the measured rungWidths/widthFactors/rungMaxWidths so every
+ * rung regenerates from `stepRatio` — the `resolveSizeRecipeInputs` contract.
+ */
+export function resolveTileSizeInputs(partial: Partial<TileSizeInputs> = {}): TileSizeInputs {
+  const scalingOverride =
+    partial.baseWidth != null || partial.stepRatio != null || partial.rungSteps != null;
+  const hasRungWidths = Object.prototype.hasOwnProperty.call(partial, "rungWidths");
+  const hasWidthFactors = Object.prototype.hasOwnProperty.call(partial, "widthFactors");
+  const hasRungMaxWidths = Object.prototype.hasOwnProperty.call(partial, "rungMaxWidths");
+
+  const resolved: TileSizeInputs = {
+    baseWidth: partial.baseWidth ?? defaultTileSizeInputs.baseWidth,
+    stepRatio: partial.stepRatio ?? defaultTileSizeInputs.stepRatio,
+    rungSteps: { ...defaultTileSizeInputs.rungSteps, ...partial.rungSteps },
+    maxRatio: partial.maxRatio ?? defaultTileSizeInputs.maxRatio,
+  };
+
+  if (hasRungWidths) {
+    resolved.rungWidths = partial.rungWidths ? { ...partial.rungWidths } : undefined;
+    if (hasWidthFactors) {
+      resolved.widthFactors = partial.widthFactors ? { ...partial.widthFactors } : undefined;
+    }
+  } else if (hasWidthFactors) {
+    resolved.widthFactors = partial.widthFactors ? { ...partial.widthFactors } : undefined;
+  } else if (!scalingOverride) {
+    resolved.rungWidths = { ...defaultTileSizeInputs.rungWidths };
+    resolved.widthFactors = { ...defaultTileSizeInputs.widthFactors };
+  }
+
+  if (hasRungMaxWidths) {
+    resolved.rungMaxWidths = partial.rungMaxWidths ? { ...partial.rungMaxWidths } : undefined;
+  } else if (!scalingOverride && !hasRungWidths && !hasWidthFactors) {
+    resolved.rungMaxWidths = { ...defaultTileSizeInputs.rungMaxWidths };
+  }
+
+  return resolved;
+}
+
+// ── Generation ────────────────────────────────────────────────
+
+function clampWidth(value: number): number {
+  return Math.max(1, Math.round(value));
+}
+
+function minWidthForRung(rung: TileSizeRung, inputs: TileSizeInputs): number {
+  const explicitPx = inputs.rungWidths?.[rung];
+  if (explicitPx != null) return clampWidth(explicitPx);
+  const factor = inputs.widthFactors?.[rung];
+  if (factor != null) return clampWidth(inputs.baseWidth * factor);
+  const step = inputs.rungSteps[rung] ?? 0;
+  return clampWidth(inputs.baseWidth * inputs.stepRatio ** step);
+}
+
+/** Derive the full ladder from resolved inputs. Tables are generated, never handwritten. */
+export function generateTileSizeLadder(inputs: TileSizeInputs): TileSizeLadder {
+  const ladder = {} as TileSizeLadder;
+  for (const rung of tileSizeRungs) {
+    const minWidth = minWidthForRung(rung, inputs);
+    const pinnedMax = inputs.rungMaxWidths?.[rung];
+    const maxWidth = Math.max(
+      minWidth,
+      pinnedMax != null ? clampWidth(pinnedMax) : clampWidth(minWidth * inputs.maxRatio),
+    );
+    ladder[rung] = { minWidth, maxWidth };
+  }
+  return ladder;
+}
+
+// ── Consumption helpers ───────────────────────────────────────
+
+export type TileRungFlexProps = {
+  flexGrow: number;
+  flexBasis: number;
+  minWidth: number;
+  maxWidth: number;
+};
+
+/**
+ * Style fragment for a tile in a wrapping flex wall (the Lookout idiom:
+ * tiles grow from `minWidth` and stop at `maxWidth`). Spread it on the tile
+ * surface; gutters stay on the container's space-knob gap.
+ */
+export function tileRungFlexProps(stop: TileSizeStop): TileRungFlexProps {
+  return {
+    flexGrow: 1,
+    flexBasis: stop.minWidth,
+    minWidth: stop.minWidth,
+    maxWidth: stop.maxWidth,
+  };
+}
+
+/**
+ * Column count for a fixed-column tile grid (the ImageGrid / springboard
+ * idiom): as many columns as fit at the rung's minWidth. `gutter` is the
+ * inter-column gap (the space knob's value), never baked into the rung.
+ *
+ * The count is min-driven on purpose: adding a column to honor `maxWidth`
+ * would, by construction of the fit, drop every cell below `minWidth`
+ * (`(fit+1)` cells at minWidth already overflow the width). `maxWidth`
+ * binds in the wrapping-flex idiom (`tileRungFlexProps`), where a tile can
+ * stop growing without forcing a new column.
+ *
+ * At the springboard's own numbers this reproduces the launcher's split:
+ * `xs` (104) with the 8px launcher gutter yields 6 columns at the 700px
+ * wide-breakpoint and 4 in the phone band.
+ */
+export function tileColumnsForWidth(width: number, stop: TileSizeStop, gutter = 0): number {
+  if (!Number.isFinite(width) || width <= 0) return 1;
+  return Math.max(1, Math.floor((width + gutter) / (stop.minWidth + gutter)));
+}
+
+// ── Media aspect (H2) ─────────────────────────────────────────
+
+/**
+ * Named media aspect ratios (width / height). A skeleton twin drawn at the
+ * wrong aspect produces the exact layout jump it exists to prevent
+ * (ImageGrid hardcoded 1; Lookout frames are 16:10).
+ */
+export const mediaAspectRatios = {
+  /** Album art, avatars, icon plates. */
+  square: 1,
+  /** Stills cameras, 4:3. */
+  photo: 4 / 3,
+  /** Desktop screen captures, 16:10 — the Lookout frame shape. */
+  screen: 16 / 10,
+  /** Video stills, 16:9. */
+  video: 16 / 9,
+  /** Portrait media, 3:4. */
+  portrait: 3 / 4,
+} as const;
+
+export type MediaAspectName = keyof typeof mediaAspectRatios;
+
+/** A named aspect or an explicit width/height number. */
+export type MediaAspect = MediaAspectName | number;
+
+/** Resolve a name or number to a positive width/height ratio (default `square`). */
+export function resolveMediaAspect(aspect?: MediaAspect | null): number {
+  if (typeof aspect === "number") {
+    return Number.isFinite(aspect) && aspect > 0 ? aspect : mediaAspectRatios.square;
+  }
+  if (aspect != null && aspect in mediaAspectRatios) return mediaAspectRatios[aspect];
+  return mediaAspectRatios.square;
+}

package/types/theme/index.d.ts

@@ -26,6 +26,7 @@ export * from "./resolveKnobs";
 export * from "./shared";
 export * from "./sizeRecipes";
 export * from "./Surface";
+export * from "./tileSizes";
 export * from "./theme";
 export * from "./Tint";
 export * from "./useResolvedKnobs";

package/types/theme/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theme/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,YAAY,EAAE,MAAM,IAAI,gBAAgB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACjF,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAE1B,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theme/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,YAAY,EAAE,MAAM,IAAI,gBAAgB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACjF,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAE5B,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC"}

package/types/theme/recipeInputs.d.ts

@@ -15,6 +15,7 @@
  * tokenHeights / sizeFactors) regenerates geometrically from
  * `baseHeight * stepRatio ** step`.
  */
+import { type TileSizeInputs, type TileSizeLadder } from "./tileSizes";
 export declare const SIZE_RECIPE_TOKENS: readonly ["$1", "$1.5", "$2", "$2.5", "$3", "$3.5", "$4", "$true", "$5", "$6"];
 export type SizeRecipeToken = (typeof SIZE_RECIPE_TOKENS)[number];
 export type SizeRecipeFamilyName = "control" | "controlCompact";
@@ -41,6 +42,11 @@ export type SizeRecipeInputs = {
     compactRatios: SizeRecipeRatios;
     radiusPx: number;
     touchFloor: number;
+    /**
+     * Tile-size ladder inputs (MPO-31). Merged over `defaultTileSizeInputs`;
+     * the ladder table derives from these the way every other table does.
+     */
+    tile?: Partial<TileSizeInputs>;
 };
 /** @deprecated Use `SizeRecipeInputs`. */
 export type RecipeInputs = SizeRecipeInputs;
@@ -91,6 +97,8 @@ export type GeneratedSizeRecipes = {
     typeVariants: Record<string, SizeRecipeTypeVariant>;
     iconVariants: Record<string, SizeRecipeIconVariant>;
     families: RecipeFamilies;
+    /** Tile-size ladder (MPO-31) — derived from `inputs.tile` over the measured defaults. */
+    tiles: TileSizeLadder;
 };
 export declare const SIZE_TOKEN_EXPONENTS: Record<SizeRecipeToken, number>;
 /** Lossless relative table: the stock Tamagui 20/24/28/32/36/40/44/52/64 ramp at baseHeight 44. */

package/types/theme/recipeInputs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recipeInputs.d.ts","sourceRoot":"","sources":["../../src/theme/recipeInputs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"recipeInputs.d.ts","sourceRoot":"","sources":["../../src/theme/recipeInputs.ts"],"names":[],"mappings":"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"}

package/types/theme/sizeRecipes.d.ts

@@ -44,6 +44,13 @@ export declare const SIZE_RECIPE_HEIGHTS_TOUCH: Record<string, number>;
 export declare const SIZE_RECIPE_RATIOS: import("./recipeInputs").SizeRecipeRatios;
 export declare const SIZE_RECIPE_COMPACT_RATIOS: import("./recipeInputs").SizeRecipeRatios;
 export declare const SIZE_RECIPE_FAMILY_NAMES: readonly ["control", "controlCompact"];
+/**
+ * Live tile-size ladder (MPO-31) — generated from `inputs.tile` over the
+ * measured defaults, adopted in place on `setSizeRecipeInputs` like every
+ * other live table. Never handwrite rungs; restyle through inputs.
+ */
+export declare const tileSizeLadder: import("./tileSizes").TileSizeLadder;
+export declare function getTileSizeLadder(): typeof tileSizeLadder;
 /** Merge `partial` over defaultRecipeInputs (not the previous override) and rewrite live tables. */
 export declare function setSizeRecipeInputs(partial?: Partial<RecipeInputs>): GeneratedSizeRecipes;
 export declare function getSizeRecipeInputs(): RecipeInputs;

package/types/theme/sizeRecipes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sizeRecipes.d.ts","sourceRoot":"","sources":["../../src/theme/sizeRecipes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,gBAAgB,EAEtB,MAAM,gBAAgB,CAAC;AAyBxB;;;GAGG;AACH,eAAO,MAAM,cAAc,yCAAmB,CAAC;AAE/C,oFAAoF;AACpF,eAAO,MAAM,WAAW,4BAAiC,CAAC;AAC1D,eAAO,MAAM,qBAAqB,+DAAqC,CAAC;AACxE,eAAO,MAAM,sBAAsB,gEAAsC,CAAC;AAC1E,eAAO,MAAM,sBAAsB,gEAAsC,CAAC;AAC1E,eAAO,MAAM,mBAAmB,wBAAiC,CAAC;AAClE,eAAO,MAAM,yBAAyB,wBAAsC,CAAC;AAC7E,eAAO,MAAM,kBAAkB,2CAAgC,CAAC;AAChE,eAAO,MAAM,0BAA0B,2CAAuC,CAAC;AAE/E,eAAO,MAAM,wBAAwB,wCAAyC,CAAC;AAmB/E,oGAAoG;AACpG,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,OAAO,CAAC,YAAY,CAAM,GAAG,oBAAoB,CAE7F;AAED,wBAAgB,mBAAmB,IAAI,YAAY,CAElD;AAED,wBAAgB,uBAAuB,IAAI,oBAAoB,CAE9D;AAED,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,gBAA4B,GAAG,gBAAgB,CAExF;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,YAAY,CAAC,QAAQ,CAAyB,GACrD,UAAU,CAEZ;AAOD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,GAC3C,UAAU,CAQZ;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,CAAA;CAAE,GAC1E,UAAU,CAKZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAE/C"}
+{"version":3,"file":"sizeRecipes.d.ts","sourceRoot":"","sources":["../../src/theme/sizeRecipes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EACL,0BAA0B,EAC1B,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,EACjB,uBAAuB,GACxB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,oBAAoB,EACpB,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAIL,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,gBAAgB,EAEtB,MAAM,gBAAgB,CAAC;AAyBxB;;;GAGG;AACH,eAAO,MAAM,cAAc,yCAAmB,CAAC;AAE/C,oFAAoF;AACpF,eAAO,MAAM,WAAW,4BAAiC,CAAC;AAC1D,eAAO,MAAM,qBAAqB,+DAAqC,CAAC;AACxE,eAAO,MAAM,sBAAsB,gEAAsC,CAAC;AAC1E,eAAO,MAAM,sBAAsB,gEAAsC,CAAC;AAC1E,eAAO,MAAM,mBAAmB,wBAAiC,CAAC;AAClE,eAAO,MAAM,yBAAyB,wBAAsC,CAAC;AAC7E,eAAO,MAAM,kBAAkB,2CAAgC,CAAC;AAChE,eAAO,MAAM,0BAA0B,2CAAuC,CAAC;AAE/E,eAAO,MAAM,wBAAwB,wCAAyC,CAAC;AAE/E;;;;GAIG;AACH,eAAO,MAAM,cAAc,sCAAgB,CAAC;AAE5C,wBAAgB,iBAAiB,IAAI,OAAO,cAAc,CAEzD;AAwBD,oGAAoG;AACpG,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,OAAO,CAAC,YAAY,CAAM,GAAG,oBAAoB,CAE7F;AAED,wBAAgB,mBAAmB,IAAI,YAAY,CAElD;AAED,wBAAgB,uBAAuB,IAAI,oBAAoB,CAE9D;AAED,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,gBAA4B,GAAG,gBAAgB,CAExF;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,YAAY,CAAC,QAAQ,CAAyB,GACrD,UAAU,CAEZ;AAOD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,GAC3C,UAAU,CAQZ;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,CAAA;CAAE,GAC1E,UAAU,CAKZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAE/C"}

package/types/theme/tileSizes.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Tile-size ladder + media-aspect vocabulary (MPO-31, design-system/12 D.3
+ * holes H1/H2).
+ *
+ * Every tile wall needs the same two decisions: HOW BIG is a tile (a small
+ * named ladder a person can pick from — the user-facing S/M/L/XL control)
+ * and WHAT SHAPE is its media (so the loading skeleton is the same shape as
+ * the image that replaces it). Before this module both were app-invented:
+ * the console's `launcherGeometry.ts` (03-our-surfaces.md DL-9) and
+ * Lookout's private `TILE_SIZES` were the same gap twice.
+ *
+ * Like the control-size recipes (LC-70 RECIPE-INPUTS), STORED INPUTS are the
+ * source of truth and the ladder table is DERIVED — never handwritten at a
+ * call site. The default rung values are the MEASURED ladders from the two
+ * real consumers, not invented numbers:
+ *
+ * | rung | minWidth | maxWidth | measured from                                  |
+ * |------|----------|----------|------------------------------------------------|
+ * | xs   | 104      | 143      | launcher icon-plate track `minmax(104px,1fr)`  |
+ * | sm   | 220      | 300      | Lookout `TILE_SIZES.s` / SPA `TILE_MIN.s`      |
+ * | md   | 320      | 440      | Lookout `TILE_SIZES.m` / SPA `TILE_MIN.m`      |
+ * | lg   | 480      | 720      | Lookout `TILE_SIZES.l` / SPA `TILE_MIN.l`      |
+ * | xl   | 720      | 1400     | Lookout `TILE_SIZES.xl` / SPA `TILE_MIN.xl`    |
+ *
+ * `{ baseWidth: 280 }` (no rungWidths / widthFactors) regenerates the whole
+ * ladder geometrically from `baseWidth * stepRatio ** step`, the same
+ * override contract `resolveSizeRecipeInputs` gives `baseHeight`.
+ *
+ * OWNERSHIP (12-one-design.md Part B): the RUNGS are universal — generated
+ * here, restyled only through recipe inputs
+ * (`setSizeRecipeInputs({ tile })` / `createDefaultThemeConfig({ recipeInputs:
+ * { tile } })`). WHICH rung a surface shows is per-app (a prop, often
+ * persisted per user). Tile gutters stay on the space knob and tile rounding
+ * on the borderRadius knob — this module never emits a gap or a radius.
+ *
+ * DENSITY (LC-76): density moves SPACE only. A compact density steps the
+ * gutters between tiles (via the space knob) and must never re-rung the
+ * ladder — tile magnitude is content scale, not chrome scale, so nothing
+ * here reads the density knob.
+ */
+export declare const tileSizeRungs: readonly ["xs", "sm", "md", "lg", "xl"];
+export type TileSizeRung = (typeof tileSizeRungs)[number];
+/** One rung: the narrowest a tile may render, and the widest. */
+export type TileSizeStop = {
+    minWidth: number;
+    maxWidth: number;
+};
+export type TileSizeLadder = Record<TileSizeRung, TileSizeStop>;
+export type TileSizeInputs = {
+    /** Desktop px min-width of the `md` rung. */
+    baseWidth: number;
+    /** Rung-to-rung ratio when regenerating geometrically. */
+    stepRatio: number;
+    /** Exponent of each rung relative to `md` (0). */
+    rungSteps: Record<TileSizeRung, number>;
+    /**
+     * Absolute desktop px min-widths. When omitted, min-widths come from
+     * `baseWidth * stepRatio ** step` (or `widthFactors`).
+     */
+    rungWidths?: Partial<Record<TileSizeRung, number>>;
+    /**
+     * Optional per-rung scale relative to `baseWidth`. Used only when
+     * `rungWidths` is omitted. Factors are `stepRatio ** exponent` otherwise.
+     */
+    widthFactors?: Partial<Record<TileSizeRung, number>>;
+    /** maxWidth = minWidth * maxRatio for any rung `rungMaxWidths` does not pin. */
+    maxRatio: number;
+    /** Absolute desktop px max-widths (measured pins win over `maxRatio`). */
+    rungMaxWidths?: Partial<Record<TileSizeRung, number>>;
+};
+export declare const tileSizeStepExponents: Record<TileSizeRung, number>;
+/** Lossless relative table: the measured 104/220/320/480/720 ramp at baseWidth 320. */
+export declare const defaultWidthFactors: Record<TileSizeRung, number>;
+export declare const defaultTileSizeInputs: TileSizeInputs;
+/**
+ * Deep copy that PRESERVES partiality: keys the caller never set stay
+ * unset, so a later `resolveTileSizeInputs` still sees them as defaults
+ * rather than explicit undefineds.
+ */
+export declare function cloneTileSizeInputs<T extends Partial<TileSizeInputs>>(inputs: T): T;
+/**
+ * Fill defaults. `{ baseWidth: 280 }` (any scaling override without explicit
+ * tables) drops the measured rungWidths/widthFactors/rungMaxWidths so every
+ * rung regenerates from `stepRatio` — the `resolveSizeRecipeInputs` contract.
+ */
+export declare function resolveTileSizeInputs(partial?: Partial<TileSizeInputs>): TileSizeInputs;
+/** Derive the full ladder from resolved inputs. Tables are generated, never handwritten. */
+export declare function generateTileSizeLadder(inputs: TileSizeInputs): TileSizeLadder;
+export type TileRungFlexProps = {
+    flexGrow: number;
+    flexBasis: number;
+    minWidth: number;
+    maxWidth: number;
+};
+/**
+ * Style fragment for a tile in a wrapping flex wall (the Lookout idiom:
+ * tiles grow from `minWidth` and stop at `maxWidth`). Spread it on the tile
+ * surface; gutters stay on the container's space-knob gap.
+ */
+export declare function tileRungFlexProps(stop: TileSizeStop): TileRungFlexProps;
+/**
+ * Column count for a fixed-column tile grid (the ImageGrid / springboard
+ * idiom): as many columns as fit at the rung's minWidth. `gutter` is the
+ * inter-column gap (the space knob's value), never baked into the rung.
+ *
+ * The count is min-driven on purpose: adding a column to honor `maxWidth`
+ * would, by construction of the fit, drop every cell below `minWidth`
+ * (`(fit+1)` cells at minWidth already overflow the width). `maxWidth`
+ * binds in the wrapping-flex idiom (`tileRungFlexProps`), where a tile can
+ * stop growing without forcing a new column.
+ *
+ * At the springboard's own numbers this reproduces the launcher's split:
+ * `xs` (104) with the 8px launcher gutter yields 6 columns at the 700px
+ * wide-breakpoint and 4 in the phone band.
+ */
+export declare function tileColumnsForWidth(width: number, stop: TileSizeStop, gutter?: number): number;
+/**
+ * Named media aspect ratios (width / height). A skeleton twin drawn at the
+ * wrong aspect produces the exact layout jump it exists to prevent
+ * (ImageGrid hardcoded 1; Lookout frames are 16:10).
+ */
+export declare const mediaAspectRatios: {
+    /** Album art, avatars, icon plates. */
+    readonly square: 1;
+    /** Stills cameras, 4:3. */
+    readonly photo: number;
+    /** Desktop screen captures, 16:10 — the Lookout frame shape. */
+    readonly screen: number;
+    /** Video stills, 16:9. */
+    readonly video: number;
+    /** Portrait media, 3:4. */
+    readonly portrait: number;
+};
+export type MediaAspectName = keyof typeof mediaAspectRatios;
+/** A named aspect or an explicit width/height number. */
+export type MediaAspect = MediaAspectName | number;
+/** Resolve a name or number to a positive width/height ratio (default `square`). */
+export declare function resolveMediaAspect(aspect?: MediaAspect | null): number;
+//# sourceMappingURL=tileSizes.d.ts.map

package/types/theme/tileSizes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tileSizes.d.ts","sourceRoot":"","sources":["../../src/theme/tileSizes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAIH,eAAO,MAAM,aAAa,yCAA0C,CAAC;AAErE,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,iEAAiE;AACjE,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;AAIhE,MAAM,MAAM,cAAc,GAAG;IAC3B,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IACxC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;IACrD,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;CACvD,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAM9D,CAAC;AAeF,uFAAuF;AACvF,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,YAAY,EAAE,MAAM,CAM5D,CAAC;AAYF,eAAO,MAAM,qBAAqB,EAAE,cASnC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,OAAO,CAAC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAOnF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,OAAO,CAAC,cAAc,CAAM,GAAG,cAAc,CAiC3F;AAiBD,4FAA4F;AAC5F,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAY7E;AAID,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,iBAAiB,CAOvE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,SAAI,GAAG,MAAM,CAGzF;AAID;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;IAC5B,uCAAuC;;IAEvC,2BAA2B;;IAE3B,gEAAgE;;IAEhE,0BAA0B;;IAE1B,2BAA2B;;CAEnB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,iBAAiB,CAAC;AAE7D,yDAAyD;AACzD,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG,MAAM,CAAC;AAEnD,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,MAAM,CAMtE"}