@swiftbrowser/web 0.1.0

package/src/layout/index.ts

@@ -0,0 +1,91 @@
+/**
+ * SwiftUI-style layout engine for the browser renderer.
+ *
+ * Pure and DOM-free: `layoutTree` takes the element tree, the device
+ * environment and a text measurer and returns a frame for every element
+ * (docs/ops-protocol.md, "Layout engine semantics").
+ *
+ * `LayoutResult.chrome` keys (all rects in screen coordinates):
+ *
+ * | kind                | keys |
+ * |---------------------|------|
+ * | `navscreen`         | `bar` (status bar + 44), `largeTitle` (only when the title is large), `back` (only when depth > 0), `title` (Phase 6: the centered inline title's rect, truncated to the room the bar items leave; absent for a large title or a `principal` toolbar), `searchField` (Phase 6: the 36px field of a `searchfield` child), `bottomBar` (Phase 6: 49 + bottom safe area, when a `bottom` toolbar is present), `content` |
+ * | `sheet`             | `grabber` (36×5), `content` (below the 20px grabber row) |
+ * | `toggle`            | `label`, `switch` (51×31 at the trailing edge) |
+ * | `button` (bordered) | `label` |
+ * | `section`           | `rows` (the inset card), `header`, `footer` (when present) |
+ * | list rows           | `row` (the full-width row rect inside the card); `navlink` rows add `label` and `chevron` (20px at the trailing edge); rows with a Phase 6 `badge` style add `badge` (the text's rect at the trailing inset, full row height) |
+ * | `scrollview`        | `content` (the content rect at scroll offset 0) |
+ * | `list`/`scrollview` | `bottomInset` (Phase 4, only under a tab bar that reaches the screen bottom: the part of the frame the bar covers; the DOM adds its height as scrollable content inset) |
+ * | `tabview`           | `bar` (49 + bottom safe area at the bottom), `item0` … `itemN-1` (equal-width 49px items in the bar), `content` (above the bar) |
+ * | `tab`               | `content` (the selected tab's safe content area: below the status bar, above the bar); non-selected tabs are in `hidden` |
+ * | `picker`            | segmented: `segment0` … `segmentN-1` (equal widths, 32 high); menu: `label` (leading), `value` (the selected option plus chevron, trailing) |
+ * | `gauge`             | `track` (the 4px bar), `fill` (the leading `value` share of the track) (Phase 6) |
+ *
+ * `LayoutResult.layouts` (Phase 6) holds, per `layout` element, the proposal
+ * it was placed with and its children's min / ideal / max sizes.
+ * | `picker`            | segmented: `segment0` … `segmentN-1` (equal widths, 32 high); menu: `label` (leading), `value` (the selected option plus chevron, trailing); inline (Phase 6): `label` (a 44 row, only for a non-empty label), `option0` … `optionN-1` (44 rows spanning the list row when there is one) |
+ * | `toolbar`           | none; the element's frame is its item group in the bar (or the whole bottom bar) and the items have ordinary frames |
+ * | `navsplit`          | `sidebar` (the sidebar column, including the leading safe-area inset), `separator` (the 1px hairline), `detail` (the detail column, including the trailing inset) (Phase 7) |
+ * | `listrow`           | Phase 8: `editControl` (the 44px leading control, full row height) while the enclosing `list` has `editing`; the row content is shifted right by 44. `swipeactions` / `contextmenu` have no keys: their children after the first are in `hidden` without frames |
+ * | `alert`             | Phase 8: `card` (270 wide, centered; a dialog's button card), `title` / `message` (when non-empty; `chromeText` carries the centered lines), `button<i>` (the i-th child's row), `ok` (the renderer-drawn OK, only without button children), `cancelCard` (dialog: the `cancel` button's own card) |
+ * | `stepper`           | Phase 8: `label`, `control` (94 × 32 at the trailing edge), `decrement` / `increment` (its halves) |
+ * | `slider`            | Phase 8: `track` (4 high, between the min / max labels), `fill` (from the track start to the thumb center), `thumb` (27 × 27) |
+ * | `datepicker`        | Phase 8: `label`, `date` / `time` (the trailing capsules, 34 high, those the `components` show) |
+ * | `sheet` (`full`)    | Phase 8: `content` only (no grabber) |
+ * | `chart`             | Phase 7: `plot` (the marks' SVG), `legend` (the legend row / column, when present), `xband` / `yband` (the axis bands, when the axis is present), `xlabel<i>` / `ylabel<i>` (one per text label of the axis), `legend<i>` (one per legend item); `chromeText` carries `xlabel<i>` / `ylabel<i>` (caption font, one line) and `fonts` the caption font for the legend. `chartitem` children have ordinary frames |
+ *
+ * `LayoutResult.hidden` lists the ids of elements that must not be shown: the
+ * non-selected tabs (which keep a frame), Phase 6, the items of a `menu`
+ * (which have none; the renderer shows them in a popover) and, Phase 7, the
+ * candidates a `viewthatfits` did not choose (no frame either). Their
+ * subtrees have no frames.
+ *
+ * `LayoutResult.chromeText` carries the text the renderer draws as chrome:
+ * `navscreen` {`title`, `largeTitle`}, `section` {`header`, `footer`}
+ * (already upper-cased and wrapped), list rows {`badge`} (Phase 6).
+ */
+
+export type {
+  DynamicTypeSize,
+  EdgeInsets,
+  FontFamily,
+  LayoutChildSizes,
+  LayoutEnvironment,
+  LayoutNode,
+  LayoutRecord,
+  LayoutResult,
+  Proposal,
+  Rect,
+  ResolvedFont,
+  Size,
+  TextAlignment,
+  TextLayout,
+  TextMeasurer,
+} from './types';
+export { layoutTree, LayoutPass, type Context as LayoutContext } from './engine';
+export {
+  defaultFont,
+  resolveFont,
+  lineHeightFor,
+  textStyleSize,
+  makeFont,
+  DYNAMIC_TYPE_SIZES,
+  TEXT_STYLE_SIZES,
+  LINE_HEIGHTS,
+  FONT_FAMILIES,
+  FONT_WEIGHTS,
+  type TextStyle,
+} from './typography';
+export { CanvasTextMeasurer, MonospaceTextMeasurer } from './measure';
+export {
+  combineDateSeconds,
+  dateInputValue,
+  formatPickerDate,
+  formatPickerTime,
+  sameUTCDay,
+  sliderFraction,
+  snapSliderValue,
+  timeInputValue,
+} from './controls';
+export { wrapText, ELLIPSIS, type WrappedText } from './text';

package/src/layout/measure.ts

@@ -0,0 +1,86 @@
+/**
+ * Text measurers. The engine only ever needs the width of a single line; the
+ * canvas-backed measurer caches by (font css, text) because the engine runs on
+ * every commit and texts rarely change.
+ */
+
+import type { ResolvedFont, TextMeasurer } from './types';
+
+type Canvas2D = Pick<CanvasRenderingContext2D, 'font' | 'measureText'>;
+
+/** Strip the `/line-height` part: some canvas implementations reject it. */
+function canvasFont(font: ResolvedFont): string {
+  return font.css.replace(/\/\d+(\.\d+)?px/, '');
+}
+
+/**
+ * Measures with a 2D canvas context (`OffscreenCanvas` when available, else a
+ * detached `<canvas>`). The context is created lazily on the first
+ * measurement, so importing this module never touches the DOM. When no canvas
+ * is available (Node), it falls back to the monospace estimate.
+ */
+export class CanvasTextMeasurer implements TextMeasurer {
+  private context: Canvas2D | null | undefined;
+  private readonly cache = new Map<string, number>();
+  private readonly fallback = new MonospaceTextMeasurer();
+  private currentFont = '';
+  private static readonly MAX_CACHE = 20_000;
+
+  measureWidth(text: string, font: ResolvedFont): number {
+    if (text.length === 0) return 0;
+    const key = `${font.css}\u0000${text}`;
+    const cached = this.cache.get(key);
+    if (cached !== undefined) return cached;
+    const context = this.acquireContext();
+    let width: number;
+    if (context) {
+      const css = canvasFont(font);
+      if (this.currentFont !== css) {
+        context.font = css;
+        this.currentFont = css;
+      }
+      width = context.measureText(text).width;
+    } else {
+      width = this.fallback.measureWidth(text, font);
+    }
+    if (this.cache.size >= CanvasTextMeasurer.MAX_CACHE) this.cache.clear();
+    this.cache.set(key, width);
+    return width;
+  }
+
+  /** Drop cached widths (call when web fonts finish loading). */
+  clearCache(): void {
+    this.cache.clear();
+  }
+
+  private acquireContext(): Canvas2D | null {
+    if (this.context !== undefined) return this.context;
+    this.context = null;
+    try {
+      const g = globalThis as unknown as {
+        OffscreenCanvas?: new (w: number, h: number) => { getContext(id: '2d'): Canvas2D | null };
+        document?: { createElement(tag: 'canvas'): { getContext(id: '2d'): Canvas2D | null } };
+      };
+      if (typeof g.OffscreenCanvas === 'function') {
+        this.context = new g.OffscreenCanvas(1, 1).getContext('2d');
+      }
+      if (!this.context && g.document && typeof g.document.createElement === 'function') {
+        this.context = g.document.createElement('canvas').getContext('2d');
+      }
+    } catch {
+      this.context = null;
+    }
+    return this.context;
+  }
+}
+
+/**
+ * Deterministic measurer for tests: 0.6em per code point, 0.3em for a space.
+ */
+export class MonospaceTextMeasurer implements TextMeasurer {
+  measureWidth(text: string, font: ResolvedFont): number {
+    let width = 0;
+    for (const ch of text) width += ch === ' ' ? 0.3 * font.size : 0.6 * font.size;
+    return width;
+  }
+}

package/src/layout/text.ts

@@ -0,0 +1,124 @@
+/**
+ * Greedy word wrapping with character fallback and `lineLimit` truncation.
+ */
+
+import type { ResolvedFont, TextMeasurer } from './types';
+
+export const ELLIPSIS = '…';
+/**
+ * Slack when comparing a line's width with the proposal. Frames are snapped
+ * to whole pixels and custom layouts round to 2 decimals, so a text proposed
+ * its own measured width can arrive a fraction narrower; half a pixel never
+ * changes a line break visibly but stops single words breaking apart.
+ */
+const EPSILON = 0.5;
+
+export interface WrappedText {
+  lines: string[];
+  /** Width of the widest line. */
+  width: number;
+  truncated: boolean;
+}
+
+/**
+ * Wrap `text` to `maxWidth` (null or non-finite = a single line per
+ * paragraph). Words are split at spaces; a word wider than the line is broken
+ * by characters. With `lineLimit`, extra lines are dropped and the last kept
+ * line is truncated with an ellipsis so it fits.
+ */
+export function wrapText(
+  text: string,
+  font: ResolvedFont,
+  maxWidth: number | null,
+  lineLimit: number | null,
+  measurer: TextMeasurer,
+): WrappedText {
+  const measure = (s: string): number => (s.length === 0 ? 0 : measurer.measureWidth(s, font));
+  const constrained = maxWidth !== null && Number.isFinite(maxWidth);
+  const paragraphs = text.split('\n');
+  let lines: string[] = [];
+  if (constrained) {
+    for (const paragraph of paragraphs) wrapParagraph(paragraph, maxWidth, measure, lines);
+  } else {
+    lines = paragraphs;
+  }
+  if (lines.length === 0) lines = [''];
+
+  let truncated = false;
+  if (lineLimit !== null && lineLimit >= 1 && lines.length > lineLimit) {
+    const kept = lines.slice(0, lineLimit - 1);
+    const rest = lines
+      .slice(lineLimit - 1)
+      .map((l) => l.trim())
+      .filter((l) => l.length > 0)
+      .join(' ');
+    kept.push(truncateLine(rest, constrained ? maxWidth : null, measure));
+    lines = kept;
+    truncated = true;
+  }
+
+  let width = 0;
+  for (const line of lines) width = Math.max(width, measure(line));
+  return { lines, width, truncated };
+}
+
+function wrapParagraph(
+  paragraph: string,
+  maxWidth: number,
+  measure: (s: string) => number,
+  out: string[],
+): void {
+  const words = paragraph.split(' ').filter((w) => w.length > 0);
+  if (words.length === 0) {
+    out.push('');
+    return;
+  }
+  let current = '';
+  for (const word of words) {
+    const candidate = current.length === 0 ? word : `${current} ${word}`;
+    if (measure(candidate) <= maxWidth + EPSILON) {
+      current = candidate;
+      continue;
+    }
+    if (current.length > 0) out.push(current);
+    if (measure(word) <= maxWidth + EPSILON) {
+      current = word;
+      continue;
+    }
+    // The word alone is wider than the line: break it by characters.
+    const chunks = breakWord(word, maxWidth, measure);
+    for (let i = 0; i < chunks.length - 1; i++) out.push(chunks[i] as string);
+    current = chunks[chunks.length - 1] ?? '';
+  }
+  out.push(current);
+}
+
+function breakWord(word: string, maxWidth: number, measure: (s: string) => number): string[] {
+  const chunks: string[] = [];
+  let chunk = '';
+  for (const ch of word) {
+    const candidate = chunk + ch;
+    if (chunk.length === 0 || measure(candidate) <= maxWidth + EPSILON) {
+      chunk = candidate; // at least one character per line
+    } else {
+      chunks.push(chunk);
+      chunk = ch;
+    }
+  }
+  if (chunk.length > 0) chunks.push(chunk);
+  return chunks;
+}
+
+function truncateLine(
+  text: string,
+  maxWidth: number | null,
+  measure: (s: string) => number,
+): string {
+  if (maxWidth === null) return text + ELLIPSIS;
+  const chars = Array.from(text);
+  while (chars.length > 0 && measure(chars.join('') + ELLIPSIS) > maxWidth + EPSILON) {
+    chars.pop();
+    while (chars.length > 0 && chars[chars.length - 1] === ' ') chars.pop();
+  }
+  return chars.join('') + ELLIPSIS;
+}

package/src/layout/types.ts

@@ -0,0 +1,153 @@
+/**
+ * Types for the SwiftUI-style layout engine (docs/ops-protocol.md, "Layout
+ * engine semantics"). Everything here is DOM-free and independent of the
+ * renderer so the engine can be unit-tested in Node.
+ */
+
+import type { AssetCatalog } from '../assets';
+
+/**
+ * A size proposal from a parent to a child. `null` means "whatever you want",
+ * `0` asks for the minimum and `Infinity` for the maximum.
+ */
+export type Proposal = { width: number | null; height: number | null };
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+/** A frame in screen coordinates (CSS px). */
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface EdgeInsets {
+  top: number;
+  leading: number;
+  bottom: number;
+  trailing: number;
+}
+
+/** The element tree the renderer keeps, in the shape the engine reads. */
+export interface LayoutNode {
+  id: number;
+  kind: string;
+  props: Record<string, unknown>;
+  children: LayoutNode[];
+}
+
+export type DynamicTypeSize =
+  | 'xSmall'
+  | 'small'
+  | 'medium'
+  | 'large'
+  | 'xLarge'
+  | 'xxLarge'
+  | 'xxxLarge'
+  | 'accessibility1'
+  | 'accessibility2'
+  | 'accessibility3'
+  | 'accessibility4'
+  | 'accessibility5';
+
+export type FontFamily = 'system' | 'rounded' | 'monospaced' | 'serif';
+
+export interface ResolvedFont {
+  family: FontFamily;
+  /** Point size in CSS px (may be fractional after Dynamic Type scaling). */
+  size: number;
+  /** CSS numeric weight, 100...900. */
+  weight: number;
+  /** Line height in CSS px (an integer). */
+  lineHeight: number;
+  /** A CSS `font` shorthand (`weight size/lineHeight family`) usable verbatim. */
+  css: string;
+}
+
+export interface TextMeasurer {
+  /** Width of one line of text in CSS px when drawn with `font`. */
+  measureWidth(text: string, font: ResolvedFont): number;
+}
+
+export interface LayoutEnvironment {
+  screen: Size;
+  safeArea: EdgeInsets;
+  dynamicTypeSize: DynamicTypeSize;
+  devicePixelRatio: number;
+  colorScheme: 'light' | 'dark';
+  /**
+   * Phase 5: the app's asset catalog manifest, for the intrinsic size of
+   * named images. Absent (or empty) when the app has no catalog; named
+   * images then measure as unknown (44×44 placeholders).
+   */
+  assets?: AssetCatalog;
+}
+
+export type TextAlignment = 'leading' | 'center' | 'trailing';
+
+export interface TextLayout {
+  font: ResolvedFont;
+  /** The exact lines the renderer must draw (already wrapped / truncated). */
+  lines: string[];
+  alignment: TextAlignment;
+  /** True when `lineLimit` cut text off (the last line ends with an ellipsis). */
+  truncated: boolean;
+}
+
+export interface LayoutResult {
+  /** Screen-coordinate frame for every element id in the tree. */
+  frames: Map<number, Rect>;
+  /** For every `text` element: the resolved font and the wrapped lines. */
+  text: Map<number, TextLayout>;
+  /**
+   * Resolved font for every `image` element, plus `navscreen` (its title font)
+   * and `section` (its header/footer font).
+   */
+  fonts: Map<number, ResolvedFont>;
+  /** For `scrollview` and `list`: the total content size (for scrolling). */
+  contentSizes: Map<number, Size>;
+  /**
+   * Sub-rects the renderer needs for compound elements, in screen coordinates.
+   * See the key list in `index.ts`.
+   */
+  chrome: Map<number, Record<string, Rect>>;
+  /**
+   * Text the renderer draws as part of chrome (not a `text` element), keyed
+   * like `chrome`: `navscreen` {title, largeTitle}, `section` {header, footer}.
+   */
+  chromeText: Map<number, Record<string, TextLayout>>;
+  /**
+   * Elements that keep their frame but are not shown: the non-selected `tab`s
+   * of a `tabview` (their content is not laid out at all).
+   */
+  hidden: Set<number>;
+  /**
+   * Phase 6: for every `layout` element that was placed, the proposal it was
+   * placed with and its children's min / ideal / max sizes (raw numbers,
+   * `Infinity` for an unbounded axis). The renderer turns these into `layout`
+   * events.
+   */
+  layouts: Map<number, LayoutRecord>;
+  /**
+   * Phase 9: the ids this run placed, hid or dropped (every other entry in
+   * the maps above is unchanged since the previous run). Absent from a
+   * one-off `layoutTree` result, which is all new.
+   */
+  changed?: Set<number>;
+}
+
+/** Host measurements of one subview of a `layout` element. */
+export interface LayoutChildSizes {
+  min: Size;
+  ideal: Size;
+  max: Size;
+}
+
+export interface LayoutRecord {
+  proposal: Proposal;
+  children: LayoutChildSizes[];
+}

package/src/layout/typography.ts

@@ -0,0 +1,188 @@
+/**
+ * Dynamic Type and font resolution.
+ *
+ * Point sizes come from Apple's Human Interface Guidelines, "Typography" >
+ * "Specifications" > "iOS, iPadOS Dynamic Type sizes" and "Larger
+ * accessibility type sizes" (https://developer.apple.com/design/human-interface-guidelines/typography).
+ * Line heights for the Large (default) sizes are the iOS values from the same
+ * tables; other sizes use round(size * 1.2).
+ */
+
+import type { DynamicTypeSize, FontFamily, LayoutEnvironment, ResolvedFont } from './types';
+
+export type TextStyle =
+  | 'largeTitle'
+  | 'title'
+  | 'title2'
+  | 'title3'
+  | 'headline'
+  | 'body'
+  | 'callout'
+  | 'subheadline'
+  | 'footnote'
+  | 'caption'
+  | 'caption2';
+
+/** Size categories in the column order of `TEXT_STYLE_SIZES`. */
+export const DYNAMIC_TYPE_SIZES: readonly DynamicTypeSize[] = [
+  'xSmall',
+  'small',
+  'medium',
+  'large',
+  'xLarge',
+  'xxLarge',
+  'xxxLarge',
+  'accessibility1',
+  'accessibility2',
+  'accessibility3',
+  'accessibility4',
+  'accessibility5',
+];
+
+const LARGE_INDEX = 3;
+
+/**
+ * Point size per text style and size category. Columns: xSmall, small,
+ * medium, large, xLarge, xxLarge, xxxLarge, AX1, AX2, AX3, AX4, AX5.
+ * (HIG "iOS, iPadOS Dynamic Type sizes" + "Larger accessibility type sizes".)
+ */
+export const TEXT_STYLE_SIZES: Record<TextStyle, readonly number[]> = {
+  largeTitle: [31, 32, 33, 34, 36, 38, 40, 44, 48, 52, 56, 60],
+  title: [25, 26, 27, 28, 30, 32, 34, 38, 43, 48, 53, 58],
+  title2: [19, 20, 21, 22, 24, 26, 28, 34, 39, 44, 50, 56],
+  title3: [17, 18, 19, 20, 22, 24, 26, 31, 37, 43, 49, 55],
+  headline: [14, 15, 16, 17, 19, 21, 23, 28, 33, 40, 47, 53],
+  body: [14, 15, 16, 17, 19, 21, 23, 28, 33, 40, 47, 53],
+  callout: [13, 14, 15, 16, 18, 20, 22, 26, 32, 38, 44, 51],
+  subheadline: [12, 13, 14, 15, 17, 19, 21, 25, 30, 36, 42, 49],
+  footnote: [12, 12, 12, 13, 15, 17, 19, 23, 27, 33, 38, 44],
+  caption: [11, 11, 11, 12, 14, 16, 18, 22, 26, 32, 37, 43],
+  caption2: [11, 11, 11, 11, 13, 15, 17, 20, 24, 29, 34, 40],
+};
+
+/** iOS line heights for the standard (Large) point sizes. */
+export const LINE_HEIGHTS: Readonly<Record<number, number>> = {
+  34: 41,
+  28: 34,
+  22: 28,
+  20: 25,
+  17: 22,
+  16: 21,
+  15: 20,
+  13: 18,
+  12: 16,
+  11: 13,
+};
+
+export const FONT_WEIGHTS: Readonly<Record<string, number>> = {
+  ultraLight: 100,
+  thin: 200,
+  light: 300,
+  regular: 400,
+  medium: 500,
+  semibold: 600,
+  bold: 700,
+  heavy: 800,
+  black: 900,
+};
+
+/** CSS family stacks; keep in sync with the renderer's stylesheet. */
+export const FONT_FAMILIES: Readonly<Record<FontFamily, string>> = {
+  system:
+    '-apple-system, BlinkMacSystemFont, "SF Pro Text", "Helvetica Neue", Inter, system-ui, sans-serif',
+  rounded:
+    'ui-rounded, "SF Pro Rounded", -apple-system, BlinkMacSystemFont, "SF Pro Text", "Helvetica Neue", Inter, system-ui, sans-serif',
+  monospaced:
+    'ui-monospace, "SF Mono", Menlo, Monaco, "Cascadia Mono", "Roboto Mono", Consolas, monospace',
+  serif: 'ui-serif, "New York", Georgia, "Times New Roman", serif',
+};
+
+const TEXT_STYLES = new Set<string>(Object.keys(TEXT_STYLE_SIZES));
+const DESIGN_TO_FAMILY: Readonly<Record<string, FontFamily>> = {
+  default: 'system',
+  rounded: 'rounded',
+  monospaced: 'monospaced',
+  serif: 'serif',
+};
+
+export function isTextStyle(value: unknown): value is TextStyle {
+  return typeof value === 'string' && TEXT_STYLES.has(value);
+}
+
+export function sizeCategoryIndex(size: DynamicTypeSize): number {
+  const index = DYNAMIC_TYPE_SIZES.indexOf(size);
+  return index < 0 ? LARGE_INDEX : index;
+}
+
+/** Point size of a text style at a Dynamic Type size category. */
+export function textStyleSize(style: TextStyle, size: DynamicTypeSize): number {
+  const row = TEXT_STYLE_SIZES[style];
+  return row[sizeCategoryIndex(size)] ?? row[LARGE_INDEX] ?? 17;
+}
+
+/** Line height for a point size: the iOS value for standard sizes, else round(size * 1.2). */
+export function lineHeightFor(size: number): number {
+  const known = LINE_HEIGHTS[size];
+  return known ?? Math.round(size * 1.2);
+}
+
+function formatPx(value: number): string {
+  // Avoid long float tails from Dynamic Type scaling in the CSS string.
+  return `${Math.round(value * 100) / 100}px`;
+}
+
+export function makeFont(family: FontFamily, size: number, weight: number): ResolvedFont {
+  const lineHeight = lineHeightFor(size);
+  const css = `${weight} ${formatPx(size)}/${lineHeight}px ${FONT_FAMILIES[family]}`;
+  return { family, size, weight, lineHeight, css };
+}
+
+/** Body text for the current `dynamicTypeSize` (17/22 at Large). */
+export function defaultFont(env: LayoutEnvironment): ResolvedFont {
+  return makeFont('system', textStyleSize('body', env.dynamicTypeSize), 400);
+}
+
+/**
+ * Apply a Font JSON object (`textStyle` | `size`, `weight`, `design`,
+ * `relativeTo`) to an inherited font. A `textStyle` or `size` defines a new
+ * font (weight defaults to regular, or semibold for `headline`; design to the
+ * system family); without either, only the given `weight`/`design` change.
+ */
+export function resolveFont(
+  fontProps: unknown,
+  inherited: ResolvedFont,
+  env: LayoutEnvironment,
+): ResolvedFont {
+  if (typeof fontProps !== 'object' || fontProps === null) return inherited;
+  const font = fontProps as Record<string, unknown>;
+  const weightName = typeof font['weight'] === 'string' ? font['weight'] : undefined;
+  const explicitWeight = weightName !== undefined ? FONT_WEIGHTS[weightName] : undefined;
+  const design = typeof font['design'] === 'string' ? font['design'] : undefined;
+  const explicitFamily = design !== undefined ? DESIGN_TO_FAMILY[design] : undefined;
+
+  const textStyle = font['textStyle'];
+  const fixedSize = font['size'];
+  let size: number;
+  let defaultWeight = 400;
+  let isNewFont = false;
+  if (isTextStyle(textStyle)) {
+    size = textStyleSize(textStyle, env.dynamicTypeSize);
+    if (textStyle === 'headline') defaultWeight = 600;
+    isNewFont = true;
+  } else if (typeof fixedSize === 'number' && Number.isFinite(fixedSize) && fixedSize > 0) {
+    size = fixedSize;
+    const relativeTo = font['relativeTo'];
+    if (isTextStyle(relativeTo)) {
+      const base = TEXT_STYLE_SIZES[relativeTo][LARGE_INDEX] ?? 17;
+      size = fixedSize * (textStyleSize(relativeTo, env.dynamicTypeSize) / base);
+    }
+    isNewFont = true;
+  } else {
+    size = inherited.size;
+  }
+
+  const weight = explicitWeight ?? (isNewFont ? defaultWeight : inherited.weight);
+  const family = explicitFamily ?? (isNewFont ? 'system' : inherited.family);
+  if (!isNewFont && weight === inherited.weight && family === inherited.family) return inherited;
+  return makeFont(family, size, weight);
+}