Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

47.5 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
//
// Paragraph layout and page setup — the controls a word processor is expected
// to have, and the geometry they are expressed in.
//
// WHAT IS HERE. Alignment, space before/after, line spacing, first-line indent
// and the two page-breaking hints (keep with next, keep together) as PARAGRAPH
// properties; page size, orientation and the four margins as DOCUMENT geometry;
// and an explicit page break the author inserts. The maths and the
// property→CSS mapping are pure functions with no DOM in them, because they are
// the part that has to be right: a wrong millimetre is a wrong printed page,
// and that is only observable on paper.
//
// ────────────────────────────────────────────────────────── 96px = 1in, why
//
// The model stores CSS px and this module converts mm and inches into them at
// 96px to the inch. That is not a convention picked here, it is the definition:
// CSS defines the px as 1/96 of an inch (css-values-4 §6.2), the browser maps
// it to physical length when it prints, and print.ts already emits
// `@page { size: 816px 1056px }` for US Letter — 8.5in × 96 and 11in × 96. So
// A4 is 210mm × 96/25.4 = 793.7px, rounded to 794. Storing mm instead and
// converting at print time would put the same constant in the pipeline one step
// later, with the geometry the editor measures no longer being the geometry the
// paper has. The rounding is to whole px and it is the ONLY lossy step: 794px
// is 210.05mm, a twentieth of a millimetre, well inside what any printer's
// unprintable margin swallows.
//
// Locale decides which unit the DIALOG speaks (in for the US, Canada and the
// Philippines, which never adopted ISO 216; mm everywhere else). The stored
// value is px in both cases — the unit is a viewer preference, exactly as the
// locale and the theme are, and it never enters the document.
//
// ──────────────────────────────────────────── absent means the document default
//
// A paragraph property is written ONLY when it differs from what the document
// says. A paragraph with no `align` is justified because the document's default
// is justify — not because someone wrote 'justify' into it. Setting a property
// to the current default DELETES the field rather than storing it.
//
// This is the whole point of the design, not tidiness. It is what makes "make
// this document ragged-right" one edit to `doc.layout.align` instead of an edit
// to nine hundred paragraphs, and it is what lets a document imported from
// elsewhere adopt this document's typography. The cost is that a paragraph
// deliberately set to the same value as the default is indistinguishable from
// one that was never touched — and that is the right trade, because a
// paragraph the author never touched SHOULD follow the document.
//
// Consequence for CSS: a block's inline style carries only its own overrides;
// document defaults are set once on the paper (custom properties, read by the
// rule block appended to styles.css). Neither is a value baked into a thousand
// elements.
//
// ────────────────────────────────────────────────── the two page-break hints
//
// `keepTogether` (do not split this paragraph across pages) and `keepNext` (do
// not part this paragraph from the one after it — the heading rule) are hints
// to PAGINATION, not CSS. paginate.ts breaks at a LINE boundary: it measures
// every line box through a TreeWalker and takes the first line whose bottom
// overflows. A keep hint means the break may only fall at a BLOCK boundary for
// the blocks that carry one, so pagination has to know which block each line
// belongs to — which it deliberately does not today ("pagination stays
// indifferent — it measures line boxes and never looks at block structure").
//
// So the change is real and it is two lines in lineBoxes plus a call: tag each
// line box with the nearest [data-id] ancestor, then group the tagged boxes
// into ATOMS (`atomize` below) and pick the break with `breakY` instead of the
// inline loop. Both are pure and tested here. The escape hatch matters as much
// as the rule: an atom TALLER than the page cannot be honoured, and pagination
// falls back to line breaking inside it — without that a keep-together
// three-page paragraph produces an empty page and then another one, forever.
//
// ══════════════════════════════════════════════════════ NEEDS FROM THE CORE
//
// Four patches. The module works without them — it applies everything to the
// editor's DOM itself and draws its own page-break rule — but without (1) the
// properties do not survive a save, and without (3) an explicit page break and
// the keep hints do not move a page boundary.
//
// (1) model.ts — THE FORMAT. Two additions and one BUG.
//
//     · `Block` gains the optional paragraph properties:
//
//         align?: 'left' | 'center' | 'right' | 'justify';
//         sb?: number;   // space before, px
//         sa?: number;   // space after, px
//         lh?: number;   // line spacing, a multiple of the font size
//         ind?: number;  // first-line indent, px
//         keepNext?: true; keepTogether?: true; breakBefore?: true;
//
//     · `PageSpec` gains `marginLeft?: number; marginRight?: number` — absent
//       means `marginX`, so every existing file and every symmetric page keeps
//       writing the one field it writes today.
//
//     · `TypeDoc` gains `layout?: { align?; sb?; sa?; lh?; ind? }` — the
//       document defaults. Absent means the built-in ones (DOC_DEFAULTS here).
//
//     · THE BUG: parseDoc BUILDS a fresh block — `const out: Block = { id,
//       kind, text }` — and copies only marks/notes/role/level/cell onto it.
//       Every OTHER field of a block is silently dropped on load. Document-level
//       unknown fields ride along on the object spread and survive; block-level
//       ones do not, so format additivity holds for the document and not for
//       the block, which is where a word processor's additive fields will
//       mostly land. This is not specific to my feature: any block property any
//       future version adds is erased by every older build that opens the file,
//       which is precisely the failure additivity exists to prevent. Minimal
//       fix, in the same place the known fields are copied:
//
//         const KNOWN = new Set(['id','kind','text','marks','notes','role','level','cell']);
//         for (const [k, v] of Object.entries(b)) if (!KNOWN.has(k)) (out as Record<string, unknown>)[k] = v;
//
//       and then CLAMP the ones we now know, as `level` already is — align to
//       the four words, lh to 0.5…4, sb/sa/ind to finite and ≥ 0, the three
//       keep flags to `true` — dropping anything else. `Block` also needs
//       `[extra: string]: unknown` for that copy to type-check, matching what
//       `TypeDoc` already declares.
//
// (2) render.ts — one line in `renderBlock`, so the editor and PRINT get the
//     same styles from the same place:
//
//         import { blockStyle } from './layout.ts';
//         ...
//         const st = blockStyle(b); if (st) el.setAttribute('style', st);
//
//     and the twin in print.ts `bodyHtml`, on the element it already builds:
//     `<${TAG[b.kind]} data-id="…" style="${blockStyle(b)}">`. `blockStyle`
//     takes the BLOCK ALONE by design — defaults belong to the paper, not to
//     ten thousand copies of themselves.
//
// (3) paginate.ts — the hints. In `lineBoxes`, tag each box:
//
//         const owner = (n: Node) => { let p = n.parentElement;
//           while (p && p !== host && !p.dataset.id) p = p.parentElement;
//           return p?.dataset.id; };
//         ... out.push({ top: …, bottom: …, id: owner(n) });
//
//     and in `paginate`, replace the inner break loop
//
//         let e = Infinity;
//         for (const b of boxes) { if (b.top < start - 0.5) continue;
//                                  if (b.bottom - start > avail) { e = b.top; break; } }
//
//     with `const e = breakY(units, start, avail);` where
//     `const units = atomize(doc.body, boxes)` is computed once, beside
//     `const boxes = …`. `LineBox` gains `id?: string`. Nothing else in that
//     file changes; with no keeps and no breaks in the document `atomize`
//     returns one atom per line and `breakY` reproduces the loop above exactly
//     — verified in scripts/test-type-layout.ts.
//
// (4) print.ts — asymmetric margins and the document defaults, both in
//     `printCss`: use `margins(doc.page)` for the page box's left/right padding
//     and for the `.t-run`/`.t-fn` insets, and emit `docVars(doc)` as
//     declarations on `body` so the printed page carries the same defaults the
//     screen does. paginate.ts's note probe (`probe.style.width`) needs the
//     same treatment: `contentBox(page).width`.
//
// Until (1) lands, the properties this module writes are lost on the next load
// — the module is complete and testable, the FILE is not durable.

import type { Block, PageSpec, TypeDoc } from './model.ts';
import { registerKey, registerPanel, type FeatureContext } from './features.ts';
import { locale, t } from './i18n.ts';

// ────────────────────────────────────────────────────────────────── geometry

/** CSS defines the px as 1/96 inch. Everything below follows from that. */
export const PX_PER_IN = 96;
export const PX_PER_MM = PX_PER_IN / 25.4;
/** points, for vertical space — typography's own unit, 72 to the inch */
export const PX_PER_PT = PX_PER_IN / 72;

export type Unit = 'mm' | 'in';

/** px per unit. One table, so no conversion is written twice. */
const PER: Record<Unit, number> = { mm: PX_PER_MM, in: PX_PER_IN };

export const toUnit = (px: number, u: Unit): number => px / PER[u];
export const fromUnit = (v: number, u: Unit): number => v * PER[u];

/**
 * Which unit this reader thinks in.
 *
 * The US, Canada and the Philippines never adopted ISO 216 and their paper is
 * sold in inches; everywhere else is millimetres. A reader's preference, so it
 * follows the VIEWER's locale and never the document — the same rule the
 * language picker follows.
 */
export function unitFor(loc: string): Unit {
  const l = loc.toLowerCase();
  return /(^|-)(us|ca|ph)(-|$)/.test(l) ? 'in' : 'mm';
}

/** Round for display: inches want 2 decimals (0.25in is a real setting), mm 0. */
export function formatLen(px: number, u: Unit): string {
  const v = toUnit(px, u);
  return u === 'in' ? String(Math.round(v * 100) / 100) : String(Math.round(v));
}

/** Read a typed length back. Returns null for anything that is not a number. */
export function parseLen(text: string, u: Unit): number | null {
  const v = Number(String(text).replace(',', '.').trim());
  return Number.isFinite(v) ? fromUnit(v, u) : null;
}

export type SizeId = 'a4' | 'letter' | 'legal';
export type Orientation = 'portrait' | 'landscape';

/**
 * The paper sizes, PORTRAIT, in px at 96dpi. Whole px: see the header — the
 * rounding is a twentieth of a millimetre and it keeps the page an integer
 * number of device-independent pixels, which is what the editor lays out in.
 */
export const PAPER: Record<SizeId, { width: number; height: number }> = {
  a4: { width: Math.round(210 * PX_PER_MM), height: Math.round(297 * PX_PER_MM) },   // 794 × 1123
  letter: { width: 8.5 * PX_PER_IN, height: 11 * PX_PER_IN },                        // 816 × 1056
  legal: { width: 8.5 * PX_PER_IN, height: 14 * PX_PER_IN },                         // 816 × 1344
};

/** Which named size this page is, either way up. Undefined = a custom size. */
export function matchSize(page: PageSpec): SizeId | undefined {
  const w = page.width, h = page.height;
  for (const id of Object.keys(PAPER) as SizeId[]) {
    const p = PAPER[id];
    if ((near(w, p.width) && near(h, p.height)) || (near(w, p.height) && near(h, p.width))) return id;
  }
  return undefined;
}
const near = (a: number, b: number) => Math.abs(a - b) <= 1;

export const orientationOf = (page: PageSpec): Orientation =>
  page.width > page.height ? 'landscape' : 'portrait';

/**
 * Turn the page. Landscape is not a separate size: it is the same sheet with
 * width and height exchanged, which is why this swaps rather than looking
 * anything up — a custom 300×500 page turns too.
 */
export function withOrientation(page: PageSpec, o: Orientation): PageSpec {
  if (orientationOf(page) === o) return { ...page };
  return { ...page, width: page.height, height: page.width };
}

/** Apply a named size, keeping the page's current orientation. */
export function withSize(page: PageSpec, id: SizeId, o = orientationOf(page)): PageSpec {
  const p = PAPER[id];
  return withOrientation({ ...page, width: p.width, height: p.height }, o);
}

/** PageSpec plus the two optional margins core does not know about yet. */
export interface PageGeom extends PageSpec {
  marginLeft?: number;
  marginRight?: number;
}
export interface Margins { top: number; right: number; bottom: number; left: number }

/** The four margins. Left and right fall back to `marginX` when absent. */
export function margins(page: PageSpec): Margins {
  const g = page as PageGeom;
  return {
    top: page.marginTop,
    bottom: page.marginBottom,
    left: g.marginLeft ?? page.marginX,
    right: g.marginRight ?? page.marginX,
  };
}

/**
 * Write four margins back.
 *
 * Symmetric margins are stored as `marginX` ALONE — the field every existing
 * file and every older build already understands. `marginLeft`/`marginRight`
 * appear only when the two sides genuinely differ (a bound document), so the
 * common page never depends on a field the core has not shipped yet.
 */
export function withMargins(page: PageSpec, m: Margins): PageGeom {
  const out: PageGeom = { ...(page as PageGeom), marginTop: m.top, marginBottom: m.bottom };
  if (near(m.left, m.right)) {
    out.marginX = Math.round(m.left);
    delete out.marginLeft;
    delete out.marginRight;
  } else {
    out.marginX = Math.round(Math.min(m.left, m.right));   // the fallback stays sane
    out.marginLeft = Math.round(m.left);
    out.marginRight = Math.round(m.right);
  }
  return out;
}

/** What is left for text once the margins have had their share. */
export function contentBox(page: PageSpec): { width: number; height: number } {
  const m = margins(page);
  return { width: page.width - m.left - m.right, height: page.height - m.top - m.bottom };
}

/** A page must leave at least this much room for text, each way. One inch. */
export const MIN_CONTENT = PX_PER_IN;
/** and the sheet itself must be at least this big, each way */
export const MIN_SHEET = 2 * PX_PER_IN;
export const MAX_SHEET = 48 * PX_PER_IN;

export type PageFault = 'sheet-small' | 'sheet-large' | 'no-width' | 'no-height';

/**
 * Is this page usable?
 *
 * Margins that leave no content area are REJECTED here rather than allowed to
 * reach pagination, where `bodyHeight` would go negative and the break loop
 * would place a page every zero pixels until its 2000-iteration guard fired.
 * The fault is returned as a CODE, not a sentence: this function is called from
 * a node rig with no locale, and the sentence belongs to the dialog.
 */
export function validatePage(page: PageSpec): { ok: true } | { ok: false; fault: PageFault } {
  if (!(page.width >= MIN_SHEET) || !(page.height >= MIN_SHEET)) return { ok: false, fault: 'sheet-small' };
  if (page.width > MAX_SHEET || page.height > MAX_SHEET) return { ok: false, fault: 'sheet-large' };
  const c = contentBox(page);
  if (c.width < MIN_CONTENT) return { ok: false, fault: 'no-width' };
  if (c.height < MIN_CONTENT) return { ok: false, fault: 'no-height' };
  return { ok: true };
}

/** The fault, said out loud. t() at call time, never frozen into a const. */
export function faultText(f: PageFault): string {
  switch (f) {
    case 'sheet-small': return t('That sheet is smaller than 2 inches — pick a bigger page.');
    case 'sheet-large': return t('That sheet is larger than any printer takes.');
    case 'no-width': return t('Those side margins leave no room for text.');
    default: return t('Those top and bottom margins leave no room for text.');
  }
}

// ─────────────────────────────────────────────────── paragraph properties

export type Align = 'left' | 'center' | 'right' | 'justify';
export const ALIGNS: readonly Align[] = ['left', 'center', 'right', 'justify'];

/** The properties a paragraph may carry, and a document may default. */
export interface ParaLayout {
  align?: Align;
  /** space before, px */
  sb?: number;
  /** space after, px */
  sa?: number;
  /** line spacing, as a multiple of the font size */
  lh?: number;
  /** first-line indent, px */
  ind?: number;
}
/** …plus the three that are page-breaking, not typography. */
export interface ParaFlags {
  keepNext?: true;
  keepTogether?: true;
  breakBefore?: true;
}
export type ParaProps = ParaLayout & ParaFlags;

/**
 * What the document means when a paragraph says nothing.
 *
 * These are the STYLESHEET's own values, restated as numbers so the resolver
 * has something to compare against. Justify is the default and stays it: the
 * Knuth–Plass line breaker is what makes justified text worth having, and a
 * word processor that defaults to ragged-right throws that away.
 */
export const DOC_DEFAULTS: Required<ParaLayout> = {
  align: 'justify',
  sb: 0,
  sa: 10,
  lh: 1.62,
  ind: Math.round(1.4 * 17 * 10) / 10,     // the stylesheet's 1.4em at 17px
};

const LAYOUT_KEYS = ['align', 'sb', 'sa', 'lh', 'ind'] as const;
const FLAG_KEYS = ['keepNext', 'keepTogether', 'breakBefore'] as const;

/** A block, read as layout properties. Core has not typed these yet. */
export const propsOf = (b: Block): ParaProps => b as unknown as ParaProps;
/** The document's own defaults, over the built-in ones. */
export const docLayout = (doc: TypeDoc): ParaLayout =>
  ((doc as { layout?: ParaLayout }).layout ?? {});

/** What actually applies to this paragraph: block over document over built-in. */
export function effective(doc: TypeDoc, b: Block): Required<ParaLayout> {
  const d = docLayout(doc), p = propsOf(b);
  const out = { ...DOC_DEFAULTS };
  for (const k of LAYOUT_KEYS) {
    const v = (p[k] ?? d[k]) as never;
    if (v !== undefined) out[k] = v;
  }
  return out;
}

/** What the document says, where the block says nothing. */
export function docEffective(doc: TypeDoc): Required<ParaLayout> {
  const d = docLayout(doc);
  const out = { ...DOC_DEFAULTS };
  for (const k of LAYOUT_KEYS) {
    const v = d[k] as never;
    if (v !== undefined) out[k] = v;
  }
  return out;
}

/**
 * Write properties onto a block — the one place absent-means-default is
 * enforced.
 *
 * A value equal to the document default is DELETED rather than stored, so a
 * paragraph only carries what makes it different. `undefined` in the patch
 * means "back to the default" and deletes too. Mutates, because it is called
 * inside store.commit on the live document.
 */
export function writeProps(doc: TypeDoc, b: Block, patch: Partial<ParaProps>): void {
  const target = b as unknown as Record<string, unknown>;
  const def = docEffective(doc);
  for (const k of LAYOUT_KEYS) {
    if (!(k in patch)) continue;
    const v = patch[k];
    if (v === undefined || v === def[k]) delete target[k];
    else target[k] = v;
  }
  for (const k of FLAG_KEYS) {
    if (!(k in patch)) continue;
    if (patch[k]) target[k] = true; else delete target[k];
  }
}

/**
 * The document defaults, as custom properties for the paper element.
 *
 * Only what differs from the stylesheet is emitted, and `data-lay` is what
 * switches the appended rule block on — a document that never touched any of
 * this renders through the untouched original rules.
 */
export function docVars(doc: TypeDoc): Record<string, string> {
  const d = docLayout(doc);
  const out: Record<string, string> = {};
  if (d.align) out['--lay-align'] = d.align;
  if (d.lh !== undefined) out['--lay-lh'] = String(d.lh);
  if (d.sb !== undefined) out['--lay-sb'] = `${d.sb}px`;
  if (d.sa !== undefined) out['--lay-sa'] = `${d.sa}px`;
  if (d.ind !== undefined) out['--lay-ind'] = `${d.ind}px`;
  return out;
}

/** The page geometry, as the custom properties styles.css already reads. */
export function pageVars(page: PageSpec): Record<string, string> {
  const m = margins(page);
  return {
    '--page-w': `${page.width}px`,
    '--page-h': `${page.height}px`,
    '--mar-x': `${page.marginX}px`,
    '--mar-l': `${m.left}px`,
    '--mar-r': `${m.right}px`,
    '--mar-t': `${m.top}px`,
    '--mar-b': `${m.bottom}px`,
  };
}

/**
 * One paragraph's own overrides, as inline CSS.
 *
 * The BLOCK ALONE — no document, on purpose. What a paragraph does not say is
 * not its business, and baking the document default into every element is how
 * "change the document's alignment" stops working.
 *
 * `padding-top: 0` rides with `sb` because the stylesheet spaces consecutive
 * paragraphs with a `margin-top: -10px; padding-top: 10px` pair; overriding
 * only the margin would leave the padding behind and add 10px to whatever the
 * author asked for.
 */
/**
 * Values a style may carry into CSS — checked HERE, where they are written,
 * not only in parseDoc: a collaborator's synced op never passes parseDoc, and
 * a string like `0;background:url(…)` needs no `<` to inject a declaration
 * (into the editor, print and the preview saved in every file).
 */
export const cssAlign = (v: unknown): string | null =>
  v === 'left' || v === 'center' || v === 'right' || v === 'justify' ? v : null;
export const cssLen = (v: unknown, lo: number, hi: number): number | null =>
  typeof v === 'number' && Number.isFinite(v) && v >= lo && v <= hi ? v : null;

export function blockStyle(b: Block): string {
  const p = propsOf(b);
  const out: string[] = [];
  const align = cssAlign(p.align), lh = cssLen(p.lh, 0.5, 4);
  const sb = cssLen(p.sb, 0, 2000), sa = cssLen(p.sa, 0, 2000), ind = cssLen(p.ind, -2000, 2000);
  if (align) out.push(`text-align:${align}`);
  if (lh !== null) out.push(`line-height:${lh}`);
  if (sb !== null) out.push(`margin-top:${sb}px`, 'padding-top:0');
  if (sa !== null) out.push(`margin-bottom:${sa}px`);
  if (ind !== null) out.push(`text-indent:${ind}px`);
  return out.join(';');
}

// ──────────────────────────────────────────────── the page-breaking hints

/** A line box as pagination measures it, tagged with the block it belongs to. */
export interface LineBox { top: number; bottom: number; id?: string }

/**
 * A unit a page break may fall between. Ordinary text gives one atom per LINE,
 * which is exactly the freedom pagination has today; a keep hint fuses lines,
 * or whole blocks, into one.
 */
export interface Atom {
  top: number;
  bottom: number;
  /** the lines inside, so an oversized atom can still be broken */
  lines: LineBox[];
  /** the author put a page break before this atom */
  forced: boolean;
}

/**
 * Group measured line boxes into break atoms.
 *
 * Reads the BODY for hints and the BOXES for geometry, and nothing else — no
 * DOM, so the interesting cases are testable in node. Boxes with no block id
 * (a stray text node) are treated as ordinary lines, which is the behaviour
 * pagination has today.
 */
export function atomize(body: readonly Block[], boxes: readonly LineBox[]): Atom[] {
  const prop = new Map<string, ParaProps>();
  const order = new Map<string, number>();
  body.forEach((b, i) => { prop.set(b.id, propsOf(b)); order.set(b.id, i); });

  // consecutive boxes of one block are a run; a box with no id is its own run
  type Run = { id?: string; lines: LineBox[] };
  const runs: Run[] = [];
  for (const box of boxes) {
    const last = runs[runs.length - 1];
    if (last && box.id && last.id === box.id) last.lines.push(box);
    else runs.push({ id: box.id, lines: [box] });
  }

  const atoms: Atom[] = [];
  for (let i = 0; i < runs.length; i++) {
    const group: Run[] = [runs[i]];
    let forced = !!(runs[i].id && prop.get(runs[i].id!)?.breakBefore);
    // keepNext fuses this run with the next — repeatedly, so a stack of
    // headings holds together. A break the author asked for WINS over a keep:
    // fusing across it would silently discard the break.
    while (i + 1 < runs.length) {
      const here = runs[i].id ? prop.get(runs[i].id!) : undefined;
      const next = runs[i + 1].id ? prop.get(runs[i + 1].id!) : undefined;
      if (!here?.keepNext || next?.breakBefore) break;
      group.push(runs[++i]);
    }
    const atomic = group.length > 1 ||
      !!(group[0].id && prop.get(group[0].id!)?.keepTogether);
    const lines = group.flatMap(r => r.lines);
    if (!lines.length) continue;
    if (atomic) {
      atoms.push({
        top: Math.min(...lines.map(l => l.top)),
        bottom: Math.max(...lines.map(l => l.bottom)),
        lines, forced,
      });
    } else {
      for (const l of lines) {
        atoms.push({ top: l.top, bottom: l.bottom, lines: [l], forced });
        forced = false;                     // only the first line carries it
      }
    }
  }
  return atoms;
}

/**
 * Where the page ends: the paper-space y of the first atom that will not fit
 * in `avail` starting from `start`, or Infinity if everything left fits.
 *
 * With no hints anywhere this is line-for-line the loop paginate.ts runs today,
 * which is the point — the hints are an addition, not a new pagination.
 *
 * The escape hatch: an atom that is taller than the whole page can never be
 * honoured, so when the overflowing atom is the one the page STARTS with, the
 * break falls at a line inside it. Without that, a keep-together paragraph
 * longer than a page would return `start` as the break and pagination would
 * emit zero-height pages until its guard tripped.
 */
export function breakY(atoms: readonly Atom[], start: number, avail: number): number {
  for (const a of atoms) {
    if (a.top < start - 0.5) continue;
    if (a.forced && a.top > start + 0.5) return a.top;
    if (a.bottom - start > avail) {
      if (a.top > start + 0.5) return a.top;
      for (const l of a.lines) {
        if (l.bottom - start > avail && l.top > start + 0.5) return l.top;
      }
      return Infinity;                      // not even one line fits; take it
    }
  }
  return Infinity;
}

// ═══════════════════════════════════════════════════════════════════ the UI
//
// Everything below touches the DOM. It is separated from the maths above by
// this line and by nothing else: the pure half is what the rig exercises, the
// impure half is what a browser needs, and neither imports anything of the
// other's.

/**
 * Icons, to the house recipe (icons.ts): a 24×24 box rendered at 16px, stroke
 * `currentColor` at width 2, round caps and joins. Declared HERE rather than in
 * icons.ts because a feature is meant to be one file plus one line in
 * registry.ts — the recipe is what must not drift, not the file it lives in.
 */
const svg = (body: string) =>
  `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">${body}</svg>`;
const ALIGN_ICON: Record<Align, string> = {
  left: svg('<line x1="3" y1="5" x2="21" y2="5"/><line x1="3" y1="9.5" x2="15" y2="9.5"/><line x1="3" y1="14" x2="21" y2="14"/><line x1="3" y1="18.5" x2="15" y2="18.5"/>'),
  center: svg('<line x1="3" y1="5" x2="21" y2="5"/><line x1="6" y1="9.5" x2="18" y2="9.5"/><line x1="3" y1="14" x2="21" y2="14"/><line x1="6" y1="18.5" x2="18" y2="18.5"/>'),
  right: svg('<line x1="3" y1="5" x2="21" y2="5"/><line x1="9" y1="9.5" x2="21" y2="9.5"/><line x1="3" y1="14" x2="21" y2="14"/><line x1="9" y1="18.5" x2="21" y2="18.5"/>'),
  justify: svg('<line x1="3" y1="5" x2="21" y2="5"/><line x1="3" y1="9.5" x2="21" y2="9.5"/><line x1="3" y1="14" x2="21" y2="14"/><line x1="3" y1="18.5" x2="21" y2="18.5"/>'),
};

/**
 * The unit this reader measures in.
 *
 * navigator.language FIRST, `locale()` only as the fallback — and that order is
 * the bug this exists because of: `locale()` returns the resolved CATALOG
 * locale, and type ships one catalog, so every reader in the world resolves to
 * plain 'en' and a US reader was offered millimetres. The catalog a person
 * reads the chrome in and the paper their printer holds are different
 * questions.
 */
const readerUnit = (): Unit =>
  unitFor(globalThis.navigator?.language || locale());

const alignLabel = (a: Align): string => a === 'left' ? t('Left')
  : a === 'center' ? t('Centre') : a === 'right' ? t('Right') : t('Justified');

// ───────────────────────────────────────────── model → the live document DOM
//
// The editor renders blocks from the model and knows nothing about layout, so
// this pass puts the geometry and the per-paragraph styles onto what it drew.
// When core patch (2) lands, renderBlock does the per-block half at render time
// and this becomes the page-geometry half alone.

let painting = false;

export function applyToDom(doc: TypeDoc, host: HTMLElement): void {
  if (painting) return;
  painting = true;
  try {
    // geometry on :root — styles.css declares --page-w and friends there
    const root = document.documentElement;
    for (const [k, v] of Object.entries(pageVars(doc.page))) root.style.setProperty(k, v);

    // document defaults on the paper, plus the switch that engages the rules
    const vars = docVars(doc);
    for (const k of ['--lay-align', '--lay-lh', '--lay-sb', '--lay-sa', '--lay-ind']) {
      host.style.removeProperty(k);
    }
    for (const [k, v] of Object.entries(vars)) host.style.setProperty(k, v);
    if (Object.keys(vars).length) host.dataset.lay = '1'; else delete host.dataset.lay;

    // per-paragraph overrides
    const byId = new Map(doc.body.map(b => [b.id, b]));
    for (const el of Array.from(host.querySelectorAll<HTMLElement>('[data-id]'))) {
      const b = byId.get(el.dataset.id!);
      if (!b) continue;
      const style = blockStyle(b);
      if (style) el.setAttribute('style', style); else el.removeAttribute('style');
      if (propsOf(b).breakBefore) el.dataset.break = '1'; else delete el.dataset.break;
    }
  } finally { painting = false; }
}

/**
 * Keep the DOM in step.
 *
 * Two signals, because the editor re-renders for reasons the store never hears
 * about (a caret move that splits a block re-renders before it commits): the
 * store for model changes, a MutationObserver on the paper for renders. The
 * observer watches childList ONLY — this pass writes style ATTRIBUTES, which
 * are a different mutation type, so it cannot re-trigger itself.
 */
function watch(ctx: FeatureContext): void {
  const host = ctx.editor.host;
  const paint = () => applyToDom(ctx.store.doc, host);
  paint();
  ctx.store.on(paint);
  new MutationObserver(paint).observe(host, { childList: true, subtree: true });
}

// ───────────────────────────────────────────────────────── selection → model

/** The blocks the selection touches, in document order. */
function selectedIds(ctx: FeatureContext): string[] {
  const host = ctx.editor.host;
  const sel = getSelection();
  const r = sel && sel.rangeCount ? sel.getRangeAt(0) : null;
  if (r && !r.collapsed && host.contains(r.commonAncestorContainer)) {
    const hit = Array.from(host.querySelectorAll<HTMLElement>('[data-id]'))
      .filter(el => r.intersectsNode(el))
      .map(el => el.dataset.id!);
    if (hit.length) return hit;
  }
  const c = ctx.editor.caret();
  return c ? [c.id] : [];
}

/** The block the panel is showing — the first of the selection. */
function focusBlock(ctx: FeatureContext): Block | undefined {
  const [id] = selectedIds(ctx);
  return id ? ctx.store.block(id) : undefined;
}

/**
 * Apply paragraph properties to the selection — ONE undo step, whether it
 * lands on one paragraph or ninety.
 *
 * The caret is taken before and restored after, because refresh() re-renders
 * the whole body and a re-render is a new set of nodes with no selection in
 * them: without this, changing alignment silently ends text entry.
 */
function applyPara(ctx: FeatureContext, patch: Partial<ParaProps>): void {
  const ids = selectedIds(ctx);
  if (!ids.length) { ctx.toast(t('Put the caret in a paragraph first')); return; }
  const set = new Set(ids);
  const caret = ctx.editor.caret();
  ctx.store.breakRun();
  ctx.store.commit(d => {
    for (const b of d.body) if (set.has(b.id)) writeProps(d, b, patch);
  });
  ctx.refresh();
  ctx.editor.setCaret(caret);
}

/** Toggle the author's page break on the paragraph the caret is in. */
function togglePageBreak(ctx: FeatureContext): void {
  const b = focusBlock(ctx);
  if (!b) { ctx.toast(t('Put the caret in a paragraph first')); return; }
  const on = !propsOf(b).breakBefore;
  if (on && ctx.store.doc.body[0]?.id === b.id) {
    // a break before the first paragraph would start the document on page 2
    ctx.toast(t('The first paragraph already starts a page'));
    return;
  }
  applyPara(ctx, { breakBefore: on ? true : undefined });
  ctx.toast(on ? t('Page break inserted') : t('Page break removed'));
}

// ────────────────────────────────────────────────────────── page setup dialog

const el = (tag: string, cls?: string): HTMLElement => {
  const n = document.createElement(tag);
  if (cls) n.className = cls;
  return n;
};

/**
 * Page setup — size, orientation, the four margins, and the document's
 * paragraph defaults.
 *
 * The defaults live here rather than in the paragraph panel because that is
 * what they are: a property of the DOCUMENT, changed once, followed by every
 * paragraph that never overrode it. Applying is a single commit, so the whole
 * dialog is one press of ⌘Z — a page resize that took three undos to put back
 * would be a trap, since it moves every page break in the file.
 */
export function openPageSetup(ctx: FeatureContext): void {
  const unit = readerUnit();
  const start = ctx.store.doc.page as PageGeom;
  let page: PageGeom = { ...start };
  let defaults: ParaLayout = { ...docLayout(ctx.store.doc) };

  const back = el('div', 't-overlay');
  const card = el('div', 't-dlg');
  card.setAttribute('role', 'dialog');
  card.setAttribute('aria-label', t('Page setup'));
  const close = () => back.remove();

  const h = (text: string) => { const n = el('h2', 't-dlg-h'); n.textContent = text; return n; };
  const row = (labelText: string, ...nodes: HTMLElement[]) => {
    const r = el('div', 't-row');
    const s = el('span');
    s.textContent = labelText;
    r.append(s, ...nodes);
    return r;
  };
  const num = (value: number, on: (v: number) => void) => {
    const i = el('input', 't-input') as HTMLInputElement;
    i.type = 'text';
    i.inputMode = 'decimal';
    i.value = formatLen(value, unit);
    i.addEventListener('input', () => {
      const px = parseLen(i.value, unit);
      if (px !== null) { on(px); sync(); }
    });
    return i;
  };
  const select = (options: Array<[string, string]>, value: string, on: (v: string) => void) => {
    const s = el('select', 't-select') as HTMLSelectElement;
    for (const [v, label] of options) {
      const o = document.createElement('option');
      o.value = v; o.textContent = label;
      s.append(o);
    }
    s.value = value;
    s.addEventListener('change', () => { on(s.value); sync(); });
    return s;
  };

  // ---- size and orientation
  const sizeSel = select(
    [['a4', 'A4'], ['letter', t('US Letter')], ['legal', t('US Legal')], ['custom', t('Custom')]],
    matchSize(page) ?? 'custom',
    v => {
      if (v === 'custom') return;
      page = { ...page, ...withSize(page, v as SizeId) };
      wIn.value = formatLen(page.width, unit);
      hIn.value = formatLen(page.height, unit);
    });
  const orientSel = select(
    [['portrait', t('Portrait')], ['landscape', t('Landscape')]],
    orientationOf(page),
    v => {
      page = { ...page, ...withOrientation(page, v as Orientation) };
      wIn.value = formatLen(page.width, unit);
      hIn.value = formatLen(page.height, unit);
    });
  const wIn = num(page.width, v => { page = { ...page, width: Math.round(v) }; });
  const hIn = num(page.height, v => { page = { ...page, height: Math.round(v) }; });

  // ---- margins
  const m0 = margins(page);
  const set = (k: keyof Margins) => (v: number) => {
    page = withMargins(page, { ...margins(page), [k]: Math.round(v) });
  };
  const mt = num(m0.top, set('top'));
  const mb = num(m0.bottom, set('bottom'));
  const ml = num(m0.left, set('left'));
  const mr = num(m0.right, set('right'));

  // ---- document paragraph defaults
  const eff = docEffective(ctx.store.doc);
  const alignSel = select(ALIGNS.map(a => [a, alignLabel(a)] as [string, string]), eff.align,
    v => { defaults = { ...defaults, align: v as Align }; });
  const lhSel = select(
    [['1', '1.0'], ['1.15', '1.15'], ['1.5', '1.5'], ['1.62', t('Book (1.62)')], ['2', '2.0']],
    String(eff.lh), v => { defaults = { ...defaults, lh: Number(v) }; });

  const readout = el('p', 't-note');
  const err = el('p', 't-note t-bad');
  const apply = el('button', 't-btn t-primary') as HTMLButtonElement;

  function sync() {
    sizeSel.value = matchSize(page) ?? 'custom';
    orientSel.value = orientationOf(page);
    const check = validatePage(page);
    const c = contentBox(page);
    readout.textContent = t('Text area: {w} × {h} {unit}', {
      w: formatLen(c.width, unit), h: formatLen(c.height, unit),
      unit: unit === 'in' ? t('in') : t('mm'),
    });
    err.textContent = check.ok ? '' : faultText(check.fault);
    err.hidden = check.ok;
    apply.disabled = !check.ok;
  }

  apply.textContent = t('Apply');
  apply.addEventListener('click', () => {
    if (!validatePage(page).ok) return;
    const caret = ctx.editor.caret();
    ctx.store.breakRun();
    // ONE commit: geometry and defaults land together, so ⌘Z puts the document
    // back exactly as it was — including every page break this moved.
    ctx.store.commit(d => {
      d.page = page as PageSpec;
      const keep: ParaLayout = {};
      for (const [k, v] of Object.entries(defaults)) {
        if (v !== undefined && v !== DOC_DEFAULTS[k as keyof ParaLayout]) {
          (keep as Record<string, unknown>)[k] = v;
        }
      }
      if (Object.keys(keep).length) (d as { layout?: ParaLayout }).layout = keep;
      else delete (d as { layout?: ParaLayout }).layout;
    });
    ctx.refresh();
    ctx.editor.setCaret(caret);
    close();
  });

  const cancel = el('button', 't-btn');
  cancel.textContent = t('Cancel');
  cancel.addEventListener('click', close);

  card.append(
    h(t('Page')),
    row(t('Size'), sizeSel, orientSel),
    row(unit === 'in' ? t('Width × height (in)') : t('Width × height (mm)'), wIn, hIn),
    h(t('Margins')),
    row(unit === 'in' ? t('Top / bottom (in)') : t('Top / bottom (mm)'), mt, mb),
    row(unit === 'in' ? t('Left / right (in)') : t('Left / right (mm)'), ml, mr),
    readout, err,
    h(t('Paragraph defaults')),
    row(t('Alignment'), alignSel),
    row(t('Line spacing'), lhSel),
  );
  const note = el('p', 't-note');
  note.textContent = t('Paragraphs follow these unless they say otherwise.');
  card.append(note);
  const foot = el('div', 't-dlg-foot');
  foot.append(cancel, apply);
  card.append(foot);
  sync();

  back.append(card);
  back.addEventListener('mousedown', e => { if (e.target === back) close(); });
  document.addEventListener('keydown', function esc(e) {
    if (e.key === 'Escape') { close(); document.removeEventListener('keydown', esc); }
  });
  document.body.append(back);
  (sizeSel as HTMLSelectElement).focus();
}

// ─────────────────────────────────────────────────────────── the panel
//
// Paragraph properties live in a PANEL rather than a dialog: they are adjusted
// while looking at the paragraph, and a modal over the page hides the one thing
// the author is judging the change by.

function mountPanel(host: HTMLElement, ctx: FeatureContext): void {
  // NO title of its own: the first group below is already "Paragraph", and
  // adding a section header above it printed the word twice in a row.
  watch(ctx);
  const unit = readerUnit();
  const wrap = el('div', 't-lay');

  const group = (title: string, ...nodes: HTMLElement[]) => {
    const g = el('div', 't-lay-g');
    const hd = el('div', 't-lay-h');
    hd.textContent = title;
    g.append(hd, ...nodes);
    return g;
  };

  // alignment
  const alignRow = el('div', 't-lay-row');
  const alignBtns = ALIGNS.map(a => {
    const b = el('button', 't-btn') as HTMLButtonElement;
    b.type = 'button';
    b.innerHTML = ALIGN_ICON[a];
    b.title = alignLabel(a);
    b.addEventListener('mousedown', e => { e.preventDefault(); applyPara(ctx, { align: a }); });
    alignRow.append(b);
    return [a, b] as const;
  });

  const field = (labelText: string, suffix: string, read: (b: Block) => string,
                 write: (v: number | undefined) => Partial<ParaProps>) => {
    const r = el('div', 't-lay-row');
    const l = el('label');
    l.textContent = labelText;
    const i = el('input', 't-input') as HTMLInputElement;
    i.type = 'text';
    i.inputMode = 'decimal';
    i.addEventListener('change', () => {
      const raw = i.value.trim();
      const v = raw === '' ? undefined : Number(raw.replace(',', '.'));
      applyPara(ctx, write(v !== undefined && Number.isFinite(v) ? v : undefined));
    });
    const s = el('span', 't-lay-unit');
    s.textContent = suffix;
    r.append(l, i, s);
    return { row: r, input: i, read };
  };

  const before = field(t('Space before'), t('pt'),
    b => trim(effective(ctx.store.doc, b).sb / PX_PER_PT),
    v => ({ sb: v === undefined ? undefined : v * PX_PER_PT }));
  const after = field(t('Space after'), t('pt'),
    b => trim(effective(ctx.store.doc, b).sa / PX_PER_PT),
    v => ({ sa: v === undefined ? undefined : v * PX_PER_PT }));
  const indent = field(t('First line'), unit === 'in' ? t('in') : t('mm'),
    b => formatLen(effective(ctx.store.doc, b).ind, unit),
    v => ({ ind: v === undefined ? undefined : fromUnit(v, unit) }));

  const lineSel = el('select', 't-select') as HTMLSelectElement;
  for (const [v, label] of [['1', '1.0'], ['1.15', '1.15'], ['1.5', '1.5'],
                            ['1.62', t('Book (1.62)')], ['2', '2.0']] as Array<[string, string]>) {
    const o = document.createElement('option');
    o.value = v; o.textContent = label;
    lineSel.append(o);
  }
  lineSel.addEventListener('change', () => applyPara(ctx, { lh: Number(lineSel.value) }));
  const lineRow = el('div', 't-lay-row');
  const lineLabel = el('label');
  lineLabel.textContent = t('Line spacing');
  lineRow.append(lineLabel, lineSel);

  const check = (labelText: string, key: keyof ParaFlags, hint: string) => {
    const l = el('label', 't-lay-check');
    const i = el('input') as HTMLInputElement;
    i.type = 'checkbox';
    i.addEventListener('change', () =>
      applyPara(ctx, { [key]: i.checked ? true : undefined } as Partial<ParaProps>));
    const s = document.createElement('span');
    s.textContent = labelText;
    l.append(i, s);
    l.title = hint;
    return { label: l, input: i, key };
  };
  const keepNext = check(t('Keep with next'), 'keepNext',
    t('This paragraph and the one after it stay on the same page.'));
  const keepTogether = check(t('Keep together'), 'keepTogether',
    t('This paragraph is never split across a page break.'));
  const breakBefore = check(t('Page break before'), 'breakBefore',
    t('Start this paragraph on a new page.'));

  const reset = el('button', 't-btn') as HTMLButtonElement;
  reset.type = 'button';
  reset.textContent = t('Use document defaults');
  reset.addEventListener('mousedown', e => {
    e.preventDefault();
    applyPara(ctx, { align: undefined, sb: undefined, sa: undefined, lh: undefined, ind: undefined });
  });

  // The page-size summary, and ONLY the summary. The "Page setup…" button that
  // used to sit beside it, under a second "Document" heading, is gone: page
  // size and orientation are rows in the props panel's Document section now,
  // and repeating the entry point here printed "Document" twice in one panel.
  const summary = el('p', 't-hint');

  wrap.append(
    group(t('Paragraph'), alignRow, lineRow, before.row, after.row, indent.row),
    group(t('Page breaking'), keepNext.label, keepTogether.label, breakBefore.label, summary),
  );
  const resetRow = el('div', 't-lay-row');
  resetRow.append(reset);
  wrap.insertBefore(resetRow, wrap.children[1]);
  host.append(wrap);

  /** Show what applies to the paragraph under the caret. */
  const refresh = () => {
    const b = focusBlock(ctx);
    const doc = ctx.store.doc;
    const e = b ? effective(doc, b) : docEffective(doc);
    for (const [a, btn] of alignBtns) btn.classList.toggle('on', e.align === a);
    lineSel.value = String(e.lh);
    if (document.activeElement !== before.input) before.input.value = b ? before.read(b) : '';
    if (document.activeElement !== after.input) after.input.value = b ? after.read(b) : '';
    if (document.activeElement !== indent.input) indent.input.value = b ? indent.read(b) : '';
    const p = b ? propsOf(b) : {};
    keepNext.input.checked = !!p.keepNext;
    keepTogether.input.checked = !!p.keepTogether;
    breakBefore.input.checked = !!p.breakBefore;
    const size = matchSize(doc.page);
    const c = contentBox(doc.page);
    summary.textContent = t('{size}, {orient} · text area {w} × {h} {unit}', {
      size: size ? size.toUpperCase() : t('Custom'),
      orient: orientationOf(doc.page) === 'portrait' ? t('Portrait') : t('Landscape'),
      w: formatLen(c.width, unit), h: formatLen(c.height, unit),
      unit: unit === 'in' ? t('in') : t('mm'),
    });
  };
  refresh();
  ctx.store.on(refresh);
  document.addEventListener('selectionchange', refresh);
}

const trim = (v: number): string => String(Math.round(v * 10) / 10);

// ─────────────────────────────────────────────────────────── registration

registerPanel({
  id: 'layout',
  // RIGHT: these are the properties of the selected paragraph, not a list of
  // what is in the document. The suite's rule, from dash/src/panels.ts.
  side: 'right',
  get label() { return t('Layout'); },
  order: 40,
  mount: mountPanel,
});

// Page setup is reached from the Document section of the properties panel;
// it is a property, not an action, and the ⋯ menu is for actions.

// NO ⋯ entry: "page break here" IS the breakBefore property, which is already
// a checkbox in the Page breaking group of this panel. Offering it twice, once
// as an action and once as a property, made the two look like different things.
// The keyboard shortcut stays — that is the fast path, not a second home.

// ⌘⏎ for the break and ⌘⇧L/E/R/J for alignment — the shortcuts every word
// processor has had for thirty years. A person should not have to learn ours.
registerKey({ key: 'enter', mod: true, run: togglePageBreak });
for (const [key, align] of [['l', 'left'], ['e', 'center'], ['r', 'right'], ['j', 'justify']] as const) {
  registerKey({ key, mod: true, shift: true, run: ctx => applyPara(ctx, { align }) });
}