@sametalmdr/word-editor 0.2.0-alpha → 0.3.0-alpha

package/dist/commands/size.js

@@ -1,368 +1,368 @@
-import { DOC_DEFAULT_STYLE_REF, locateParagraph, paragraphLength, withMarkValue } from "../model/node.js";
-import { createPosition, isCollapsed, paragraphIdOf, selectionRange } from "../model/position.js";
-import { effectiveRunSize, sizeRanges } from "../model/runs.js";
-import { setSizeStep } from "../model/step.js";
-import { createTransaction } from "../model/transaction.js";
-import { marksAt } from "./marks.js";
-
-// ADR-0028: font-size is editable via delta ("current size ± one step"), not
-// toggled like bold/italic/underline — see SetSizeStep's own doc comment
-// (model/step.js) for why that made a new step type unavoidable rather than
-// a boolean-shaped mark. This module is toggleMark's counterpart.
-
-/** One UI step, half-points (1pt) — a doubled OOXML unit, doubled here to
- * stay an integer. Linear, not Word's own non-linear size table
- * (8,9,10,10.5,...) — a small, reversible parameter, not an architectural
- * choice (ADR-0028's own "Kapsam dışı"). */
-const STEP_HALF_POINTS = 2;
-
-/** 1pt — Word's own reported floor (word.tips.net, a secondary source; the
- * OOXML schema itself, ST_HpsMeasure, sets no minimum beyond "unsigned"). */
-const MIN_SZ = 2;
-
-/** 1638pt — Word's own reported UI ceiling, same secondary source. NOT
- * verified against a primary ECMA-376/Microsoft spec page (ADR-0028's own
- * DOĞRULANMALI); kept as a safety backstop, not a claimed exact limit.
- *
- * 🔴 ADR-0031 raised the stakes without raising the confidence. While
- * `setSizeDelta` was the only caller this was unreachable in practice — you
- * would have to press A+ from 11pt to 1638pt one point at a time. A free-text
- * box reaches it in one keystroke, so a WRONG ceiling now silently clips a
- * real user's real value, and `noteUnverifiedAssumption` does not save them:
- * `app.html` deliberately renders no report at all. Closing this needs a
- * primary source or a real-Word experiment at 1638/1639pt. */
-const MAX_SZ = 3276;
-
-/** `Transaction.noteUnverifiedAssumption`'s message when a resize actually
- * hits `MAX_SZ` — the command-layer counterpart of `ImportReport.
- * unverifiedAssumptions` (`io/ooxml/import.js`), dynamic rather than static:
- * recorded only when the ceiling is genuinely exercised, not on every call. */
-const MAX_SZ_ASSUMPTION =
-  "font size clamped to the 3276-half-point (1638pt) ceiling — sourced only from a " +
-  "secondary reference (word.tips.net), not a primary ECMA-376/Microsoft spec page " +
-  "(ADR-0028's own DOĞRULANMALI; ST_HpsMeasure itself sets no upper bound).";
-
-/**
- * Clamps to `[MIN_SZ, MAX_SZ]`, noting on `tr` the first time this call
- * actually hits the CEILING (not the floor: 1pt is schema-consistent —
- * `ST_HpsMeasure` is merely "unsigned" — and matches Word's own reported
- * floor too, so it carries no such uncertainty).
- * @param {import("../model/transaction.js").TransactionBuilder} tr
- * @param {number} value
- * @returns {number}
- */
-function clampSize(tr, value) {
-  const clamped = Math.min(MAX_SZ, Math.max(MIN_SZ, Math.round(value)));
-  if (clamped === MAX_SZ && value > MAX_SZ) {
-    tr.noteUnverifiedAssumption(MAX_SZ_ASSUMPTION);
-  }
-  return clamped;
-}
-
-/**
- * @param {import("../model/node.js").StyleTable} styles
- * @returns {number}
- */
-function docDefaultFallback(styles) {
-  const raw = styles[DOC_DEFAULT_STYLE_REF]?.sz;
-  if (typeof raw === "string") {
-    const n = Number.parseInt(raw, 10);
-    if (Number.isFinite(n)) {
-      return n;
-    }
-  }
-  // Only reached for a Doc that never went through import.js at all (no
-  // docDefaults sentinel was ever written) — createEmptyDoc's very first box.
-  // 22 half-points = 11pt, the corpus's own most common "at baseline" size
-  // (5,447 runs, docs/paragraph-properties-measurement.md's 2026-08-30 ek).
-  return 22;
-}
-
-/**
- * Shared by `effectiveSize` (reads live document state) and
- * `setSizeDelta`'s collapsed branch (must read `current`, which already
- * folds in a pending `storedMarks.sz` — calling `effectiveSize(doc, pos)`
- * there would re-derive straight from `doc` and silently ignore any size
- * not yet committed to the document, breaking repeated presses).
- * @param {import("../model/node.js").StyleTable} styles
- * @param {import("../model/node.js").Marks} marks
- * @returns {number}
- */
-function resolveSize(styles, marks) {
-  const resolved = effectiveRunSize(styles, { type: "text", text: "", marks });
-  return resolved ?? docDefaultFallback(styles);
-}
-
-/**
- * The effective font size (half-points) at a position — `marksAt`'s
- * left-biased mark resolution, then `Marks.sz` if set there, then
- * `Doc.styles[rPrRef].sz`, then the document's own docDefaults sentinel.
- * @param {import("../model/node.js").Doc} doc
- * @param {import("../model/position.js").Position} pos
- * @returns {number}
- */
-export function effectiveSize(doc, pos) {
-  return resolveSize(doc.styles, marksAt(doc, pos));
-}
-
-/**
- * @typedef {object} SizeSegment
- * @property {import("../model/position.js").Position} from
- * @property {import("../model/position.js").Position} to
- * @property {number} current  effective half-points, UNCLAMPED
- */
-
-/**
- * The one run-cluster walk every size command in this module shares — a RANGE
- * selection resolved into `sizeRanges` segments, each already addressed by
- * `Position` and already carrying its effective size.
- *
- * Three return shapes, and the two empty-looking ones are deliberately NOT
- * merged: collapsing them here would make it impossible for a caller to tell
- * "the selection was refused" from "the selection resolved but covers no
- * characters", and they mean different things to a setter than to a readout.
- *  - `null` — refused: the range would not resolve, or it crosses containers
- *    (ADR-0007, the same rule marks follow).
- *  - `[]` — resolved, but covers no characters at all (an empty paragraph).
- *  - otherwise — one entry per run-cluster, in document order.
- *
- * **It does not clamp.** `clampSize` needs a live transaction to note the
- * ceiling on, and a readout must report the document's real size even when
- * that size is outside the range a command would write — clamping here would
- * make `sizeAtSelection` lie about a genuine 4000-half-point run.
- *
- * @param {import("../model/node.js").Doc} doc
- * @param {import("../model/position.js").Selection} selection
- * @returns {SizeSegment[] | null}
- */
-function selectionSizeSegments(doc, selection) {
-  const range = selectionRange(doc, selection);
-  if (range === null) {
-    return null;
-  }
-  const fromAt = locateParagraph(doc, paragraphIdOf(range.from));
-  const toAt = locateParagraph(doc, paragraphIdOf(range.to));
-  if (fromAt === null || toAt === null || fromAt.containerIndex !== toAt.containerIndex) {
-    return null;
-  }
-
-  const container = fromAt.container;
-  const fallback = docDefaultFallback(doc.styles);
-  /** @type {SizeSegment[]} */
-  const segments = [];
-
-  for (let i = fromAt.paraIndex; i <= toAt.paraIndex; i += 1) {
-    const para = container.content[i];
-    const start = i === fromAt.paraIndex ? range.from.offset : 0;
-    const end = i === toAt.paraIndex ? range.to.offset : paragraphLength(para);
-    if (end <= start) {
-      continue;
-    }
-    for (const seg of sizeRanges(doc.styles, para.content, start, end)) {
-      segments.push({
-        from: createPosition(container.id, para.id, seg.from),
-        to: createPosition(container.id, para.id, seg.to),
-        // `sizeRanges` reports `undefined` for "no override, inherited"; every
-        // caller here wants the EFFECTIVE size, so the fallback is applied once.
-        current: seg.value ?? fallback,
-      });
-    }
-  }
-  return segments;
-}
-
-/**
- * The size shared by EVERY run the selection touches, or null when they
- * disagree — `alignmentAtSelection`/`indentAtSelection`'s run-level twin, and
- * what a size READOUT should show ("a value means every selected run is
- * already this; blank means mixed").
- *
- * Two things it is deliberately NOT:
- *  - not `effectiveSize(doc, selection.head)`: that answers "what size at this
- *    one point", which for a range spanning 9pt and 11pt text would report 9pt
- *    as though the whole selection were 9pt.
- *  - not a setter. Absolute assignment is `setSizeAbsolute` (ADR-0031), a
- *    separate command with its own clamp and inherit story.
- *
- * A COLLAPSED caret folds in a pending `storedMarks.sz`, exactly as
- * `setSizeDelta`'s own collapsed branch does — otherwise pressing A+ with no
- * selection would change what the next typed character will be while the
- * readout kept showing the old size.
- *
- * @param {import("../state/editor-state.js").EditorState} state
- * @returns {number | null}  half-points, or null when mixed / unresolvable
- */
-export function sizeAtSelection(state) {
-  const { doc, selection } = state;
-
-  if (isCollapsed(selection)) {
-    return resolveSize(doc.styles, state.storedMarks ?? marksAt(doc, selection.head));
-  }
-
-  // The very walk the setters act on, so the readout can never disagree with
-  // what a resize would actually change.
-  const segments = selectionSizeSegments(doc, selection);
-  if (segments === null) {
-    return null;
-  }
-
-  /** @type {number | null} */
-  let seen = null;
-  for (const seg of segments) {
-    if (seen === null) {
-      seen = seg.current;
-    } else if (seen !== seg.current) {
-      return null; // mixed — the readout goes blank
-    }
-  }
-  // Still null when the range covered no characters at all (an empty
-  // paragraph): blank, never an invented number.
-  return seen;
-}
-
-/**
- * Increases or decreases the font size by one step (`STEP_HALF_POINTS`,
- * signed — pass a negative `steps` to decrease).
- *
- * **Collapsed selection:** mirrors `toggleMark`'s storedMarks path — no
- * document change, the pending size rides on `storedMarks` (via
- * `withMarkValue`, not `withMark`) so the next typed character comes out at
- * the new size.
- *
- * **Range selection:** unlike a boolean toggle's single target value, each
- * existing run-cluster in the selection starts from its OWN current size
- * (`sizeRanges`, via `selectionSizeSegments`) — so a mixed-size selection
- * increases each stretch from wherever it already was, not to one uniform
- * value. Contrast `setSizeAbsolute`, which does the opposite on purpose.
- *
- * @param {import("../state/editor-state.js").EditorState} state
- * @param {number} steps  positive = larger, negative = smaller
- * @returns {import("../model/transaction.js").Transaction | null}
- */
-export function setSizeDelta(state, steps) {
-  const { doc, selection } = state;
-  const delta = steps * STEP_HALF_POINTS;
-
-  if (isCollapsed(selection)) {
-    const current = state.storedMarks ?? marksAt(doc, selection.head);
-    const currentSize = resolveSize(doc.styles, current);
-    const tr = createTransaction(doc, selection, "format");
-    tr.setStoredMarks(withMarkValue(current, "sz", clampSize(tr, currentSize + delta)));
-    return tr.build();
-  }
-
-  const segments = selectionSizeSegments(doc, selection);
-  if (segments === null || segments.length === 0) {
-    return null;
-  }
-
-  // Created before the clamp walk (not after, like toggleMark's range
-  // branch) — clampSize needs a live `tr` to note the ceiling on, the
-  // moment it is actually hit.
-  const tr = createTransaction(doc, selection, "format");
-
-  tr.step(
-    setSizeStep(
-      segments.map((seg) => ({
-        from: seg.from,
-        to: seg.to,
-        value: clampSize(tr, seg.current + delta),
-      })),
-    ),
-  );
-  if (!tr.changesDoc) {
-    return null;
-  }
-
-  // Sizes never move characters, so the selection is preserved as-is.
-  tr.setSelection(selection);
-  tr.setStoredMarks(null);
-  return tr.build();
-}
-
-/**
- * Assigns ONE absolute size to everything the selection touches — the
- * combobox's write path (ADR-0031), `setSizeDelta`'s counterpart.
- *
- * Deliberately NOT implemented as a delta: it never reads the current size,
- * so a mixed-size selection comes out UNIFORM rather than each stretch
- * shifting from wherever it already was. That difference is the whole point
- * of the command — it is what "pick 14pt" means in Word, and what "press A+"
- * does not mean.
- *
- * **Assigning the target to a run that merely INHERITS it still writes an
- * explicit override** and still produces a real transaction. Word does the
- * same (choosing a point size writes `w:sz`), but it is worth stating: the
- * box can read 11 and picking 11 can still change the document.
- *
- * @param {import("../state/editor-state.js").EditorState} state
- * @param {number} targetSz  HALF-POINTS, the model's own unit
- * @returns {import("../model/transaction.js").Transaction | null}
- */
-export function setSizeAbsolute(state, targetSz) {
-  const { doc, selection } = state;
-
-  // clampSize is Math.round/min/max, and every one of those passes NaN
-  // straight through — unreachable while `setSizeDelta` was the only caller
-  // (its steps are always ±1), reachable the moment a text field feeds this
-  // one. A NaN here would land in `marks.sz` and from there in `w:sz`.
-  if (!Number.isFinite(targetSz)) {
-    return null;
-  }
-
-  if (isCollapsed(selection)) {
-    // Mirrors setSizeDelta's collapsed branch, minus the one line that
-    // matters: no `resolveSize`, because an absolute target does not care
-    // what the current size is. The two branches are NOT factored together —
-    // they differ in exactly that line, and SZ4's mutation targets it.
-    const current = state.storedMarks ?? marksAt(doc, selection.head);
-    const tr = createTransaction(doc, selection, "format");
-    tr.setStoredMarks(withMarkValue(current, "sz", clampSize(tr, targetSz)));
-    return tr.build();
-  }
-
-  const segments = selectionSizeSegments(doc, selection);
-  if (segments === null || segments.length === 0) {
-    return null;
-  }
-
-  const tr = createTransaction(doc, selection, "format");
-  // ONE clamp for one target — unlike setSizeDelta, which must clamp each
-  // cluster separately because each starts from its own size.
-  const value = clampSize(tr, targetSz);
-
-  tr.step(setSizeStep(segments.map((seg) => ({ from: seg.from, to: seg.to, value }))));
-  if (!tr.changesDoc) {
-    return null;
-  }
-
-  tr.setSelection(selection);
-  tr.setStoredMarks(null);
-  return tr.build();
-}
-
-/**
- * Parses what a user typed into the point-size box into the model's own
- * half-point unit. Lives here rather than in `examples/` because it is the
- * only real logic at that UI boundary, and nothing under `examples/` is
- * loaded by any Node test (measured — `SESSION-LOG.md` Ek 57).
- *
- * Accepts a comma as the decimal separator: the UI is Turkish, and the
- * numpad's decimal key produces a comma under a Turkish keyboard layout.
- *
- * **It does not clamp.** Range enforcement belongs to the command, which has
- * a transaction to disclose a ceiling hit on; keeping the two apart is what
- * lets `"5000"` parse cleanly and then be clamped visibly.
- *
- * @param {string} text
- * @returns {number | null}  half-points, or null when there is no number here
- */
-export function parseSizePoints(text) {
-  const points = Number.parseFloat(text.trim().replace(",", "."));
-  if (!Number.isFinite(points)) {
-    return null;
-  }
-  // Half-points are integers by definition (ST_HpsMeasure is unsigned
-  // decimal), so 11.3pt resolves to the nearest half-point, 11.5.
-  return Math.round(points * 2);
-}
+import { DOC_DEFAULT_STYLE_REF, locateParagraph, paragraphLength, withMarkValue } from "../model/node.js";
+import { createPosition, isCollapsed, paragraphIdOf, selectionRange } from "../model/position.js";
+import { effectiveRunSize, sizeRanges } from "../model/runs.js";
+import { setSizeStep } from "../model/step.js";
+import { createTransaction } from "../model/transaction.js";
+import { marksAt } from "./marks.js";
+
+// ADR-0028: font-size is editable via delta ("current size ± one step"), not
+// toggled like bold/italic/underline — see SetSizeStep's own doc comment
+// (model/step.js) for why that made a new step type unavoidable rather than
+// a boolean-shaped mark. This module is toggleMark's counterpart.
+
+/** One UI step, half-points (1pt) — a doubled OOXML unit, doubled here to
+ * stay an integer. Linear, not Word's own non-linear size table
+ * (8,9,10,10.5,...) — a small, reversible parameter, not an architectural
+ * choice (ADR-0028's own "Kapsam dışı"). */
+const STEP_HALF_POINTS = 2;
+
+/** 1pt — Word's own reported floor (word.tips.net, a secondary source; the
+ * OOXML schema itself, ST_HpsMeasure, sets no minimum beyond "unsigned"). */
+const MIN_SZ = 2;
+
+/** 1638pt — Word's own reported UI ceiling, same secondary source. NOT
+ * verified against a primary ECMA-376/Microsoft spec page (ADR-0028's own
+ * DOĞRULANMALI); kept as a safety backstop, not a claimed exact limit.
+ *
+ * 🔴 ADR-0031 raised the stakes without raising the confidence. While
+ * `setSizeDelta` was the only caller this was unreachable in practice — you
+ * would have to press A+ from 11pt to 1638pt one point at a time. A free-text
+ * box reaches it in one keystroke, so a WRONG ceiling now silently clips a
+ * real user's real value, and `noteUnverifiedAssumption` does not save them:
+ * `app.html` deliberately renders no report at all. Closing this needs a
+ * primary source or a real-Word experiment at 1638/1639pt. */
+const MAX_SZ = 3276;
+
+/** `Transaction.noteUnverifiedAssumption`'s message when a resize actually
+ * hits `MAX_SZ` — the command-layer counterpart of `ImportReport.
+ * unverifiedAssumptions` (`io/ooxml/import.js`), dynamic rather than static:
+ * recorded only when the ceiling is genuinely exercised, not on every call. */
+const MAX_SZ_ASSUMPTION =
+  "font size clamped to the 3276-half-point (1638pt) ceiling — sourced only from a " +
+  "secondary reference (word.tips.net), not a primary ECMA-376/Microsoft spec page " +
+  "(ADR-0028's own DOĞRULANMALI; ST_HpsMeasure itself sets no upper bound).";
+
+/**
+ * Clamps to `[MIN_SZ, MAX_SZ]`, noting on `tr` the first time this call
+ * actually hits the CEILING (not the floor: 1pt is schema-consistent —
+ * `ST_HpsMeasure` is merely "unsigned" — and matches Word's own reported
+ * floor too, so it carries no such uncertainty).
+ * @param {import("../model/transaction.js").TransactionBuilder} tr
+ * @param {number} value
+ * @returns {number}
+ */
+function clampSize(tr, value) {
+  const clamped = Math.min(MAX_SZ, Math.max(MIN_SZ, Math.round(value)));
+  if (clamped === MAX_SZ && value > MAX_SZ) {
+    tr.noteUnverifiedAssumption(MAX_SZ_ASSUMPTION);
+  }
+  return clamped;
+}
+
+/**
+ * @param {import("../model/node.js").StyleTable} styles
+ * @returns {number}
+ */
+function docDefaultFallback(styles) {
+  const raw = styles[DOC_DEFAULT_STYLE_REF]?.sz;
+  if (typeof raw === "string") {
+    const n = Number.parseInt(raw, 10);
+    if (Number.isFinite(n)) {
+      return n;
+    }
+  }
+  // Only reached for a Doc that never went through import.js at all (no
+  // docDefaults sentinel was ever written) — createEmptyDoc's very first box.
+  // 22 half-points = 11pt, the corpus's own most common "at baseline" size
+  // (5,447 runs, docs/paragraph-properties-measurement.md's 2026-08-30 ek).
+  return 22;
+}
+
+/**
+ * Shared by `effectiveSize` (reads live document state) and
+ * `setSizeDelta`'s collapsed branch (must read `current`, which already
+ * folds in a pending `storedMarks.sz` — calling `effectiveSize(doc, pos)`
+ * there would re-derive straight from `doc` and silently ignore any size
+ * not yet committed to the document, breaking repeated presses).
+ * @param {import("../model/node.js").StyleTable} styles
+ * @param {import("../model/node.js").Marks} marks
+ * @returns {number}
+ */
+function resolveSize(styles, marks) {
+  const resolved = effectiveRunSize(styles, { type: "text", text: "", marks });
+  return resolved ?? docDefaultFallback(styles);
+}
+
+/**
+ * The effective font size (half-points) at a position — `marksAt`'s
+ * left-biased mark resolution, then `Marks.sz` if set there, then
+ * `Doc.styles[rPrRef].sz`, then the document's own docDefaults sentinel.
+ * @param {import("../model/node.js").Doc} doc
+ * @param {import("../model/position.js").Position} pos
+ * @returns {number}
+ */
+export function effectiveSize(doc, pos) {
+  return resolveSize(doc.styles, marksAt(doc, pos));
+}
+
+/**
+ * @typedef {object} SizeSegment
+ * @property {import("../model/position.js").Position} from
+ * @property {import("../model/position.js").Position} to
+ * @property {number} current  effective half-points, UNCLAMPED
+ */
+
+/**
+ * The one run-cluster walk every size command in this module shares — a RANGE
+ * selection resolved into `sizeRanges` segments, each already addressed by
+ * `Position` and already carrying its effective size.
+ *
+ * Three return shapes, and the two empty-looking ones are deliberately NOT
+ * merged: collapsing them here would make it impossible for a caller to tell
+ * "the selection was refused" from "the selection resolved but covers no
+ * characters", and they mean different things to a setter than to a readout.
+ *  - `null` — refused: the range would not resolve, or it crosses containers
+ *    (ADR-0007, the same rule marks follow).
+ *  - `[]` — resolved, but covers no characters at all (an empty paragraph).
+ *  - otherwise — one entry per run-cluster, in document order.
+ *
+ * **It does not clamp.** `clampSize` needs a live transaction to note the
+ * ceiling on, and a readout must report the document's real size even when
+ * that size is outside the range a command would write — clamping here would
+ * make `sizeAtSelection` lie about a genuine 4000-half-point run.
+ *
+ * @param {import("../model/node.js").Doc} doc
+ * @param {import("../model/position.js").Selection} selection
+ * @returns {SizeSegment[] | null}
+ */
+function selectionSizeSegments(doc, selection) {
+  const range = selectionRange(doc, selection);
+  if (range === null) {
+    return null;
+  }
+  const fromAt = locateParagraph(doc, paragraphIdOf(range.from));
+  const toAt = locateParagraph(doc, paragraphIdOf(range.to));
+  if (fromAt === null || toAt === null || fromAt.containerIndex !== toAt.containerIndex) {
+    return null;
+  }
+
+  const container = fromAt.container;
+  const fallback = docDefaultFallback(doc.styles);
+  /** @type {SizeSegment[]} */
+  const segments = [];
+
+  for (let i = fromAt.paraIndex; i <= toAt.paraIndex; i += 1) {
+    const para = container.content[i];
+    const start = i === fromAt.paraIndex ? range.from.offset : 0;
+    const end = i === toAt.paraIndex ? range.to.offset : paragraphLength(para);
+    if (end <= start) {
+      continue;
+    }
+    for (const seg of sizeRanges(doc.styles, para.content, start, end)) {
+      segments.push({
+        from: createPosition(container.id, para.id, seg.from),
+        to: createPosition(container.id, para.id, seg.to),
+        // `sizeRanges` reports `undefined` for "no override, inherited"; every
+        // caller here wants the EFFECTIVE size, so the fallback is applied once.
+        current: seg.value ?? fallback,
+      });
+    }
+  }
+  return segments;
+}
+
+/**
+ * The size shared by EVERY run the selection touches, or null when they
+ * disagree — `alignmentAtSelection`/`indentAtSelection`'s run-level twin, and
+ * what a size READOUT should show ("a value means every selected run is
+ * already this; blank means mixed").
+ *
+ * Two things it is deliberately NOT:
+ *  - not `effectiveSize(doc, selection.head)`: that answers "what size at this
+ *    one point", which for a range spanning 9pt and 11pt text would report 9pt
+ *    as though the whole selection were 9pt.
+ *  - not a setter. Absolute assignment is `setSizeAbsolute` (ADR-0031), a
+ *    separate command with its own clamp and inherit story.
+ *
+ * A COLLAPSED caret folds in a pending `storedMarks.sz`, exactly as
+ * `setSizeDelta`'s own collapsed branch does — otherwise pressing A+ with no
+ * selection would change what the next typed character will be while the
+ * readout kept showing the old size.
+ *
+ * @param {import("../state/editor-state.js").EditorState} state
+ * @returns {number | null}  half-points, or null when mixed / unresolvable
+ */
+export function sizeAtSelection(state) {
+  const { doc, selection } = state;
+
+  if (isCollapsed(selection)) {
+    return resolveSize(doc.styles, state.storedMarks ?? marksAt(doc, selection.head));
+  }
+
+  // The very walk the setters act on, so the readout can never disagree with
+  // what a resize would actually change.
+  const segments = selectionSizeSegments(doc, selection);
+  if (segments === null) {
+    return null;
+  }
+
+  /** @type {number | null} */
+  let seen = null;
+  for (const seg of segments) {
+    if (seen === null) {
+      seen = seg.current;
+    } else if (seen !== seg.current) {
+      return null; // mixed — the readout goes blank
+    }
+  }
+  // Still null when the range covered no characters at all (an empty
+  // paragraph): blank, never an invented number.
+  return seen;
+}
+
+/**
+ * Increases or decreases the font size by one step (`STEP_HALF_POINTS`,
+ * signed — pass a negative `steps` to decrease).
+ *
+ * **Collapsed selection:** mirrors `toggleMark`'s storedMarks path — no
+ * document change, the pending size rides on `storedMarks` (via
+ * `withMarkValue`, not `withMark`) so the next typed character comes out at
+ * the new size.
+ *
+ * **Range selection:** unlike a boolean toggle's single target value, each
+ * existing run-cluster in the selection starts from its OWN current size
+ * (`sizeRanges`, via `selectionSizeSegments`) — so a mixed-size selection
+ * increases each stretch from wherever it already was, not to one uniform
+ * value. Contrast `setSizeAbsolute`, which does the opposite on purpose.
+ *
+ * @param {import("../state/editor-state.js").EditorState} state
+ * @param {number} steps  positive = larger, negative = smaller
+ * @returns {import("../model/transaction.js").Transaction | null}
+ */
+export function setSizeDelta(state, steps) {
+  const { doc, selection } = state;
+  const delta = steps * STEP_HALF_POINTS;
+
+  if (isCollapsed(selection)) {
+    const current = state.storedMarks ?? marksAt(doc, selection.head);
+    const currentSize = resolveSize(doc.styles, current);
+    const tr = createTransaction(doc, selection, "format");
+    tr.setStoredMarks(withMarkValue(current, "sz", clampSize(tr, currentSize + delta)));
+    return tr.build();
+  }
+
+  const segments = selectionSizeSegments(doc, selection);
+  if (segments === null || segments.length === 0) {
+    return null;
+  }
+
+  // Created before the clamp walk (not after, like toggleMark's range
+  // branch) — clampSize needs a live `tr` to note the ceiling on, the
+  // moment it is actually hit.
+  const tr = createTransaction(doc, selection, "format");
+
+  tr.step(
+    setSizeStep(
+      segments.map((seg) => ({
+        from: seg.from,
+        to: seg.to,
+        value: clampSize(tr, seg.current + delta),
+      })),
+    ),
+  );
+  if (!tr.changesDoc) {
+    return null;
+  }
+
+  // Sizes never move characters, so the selection is preserved as-is.
+  tr.setSelection(selection);
+  tr.setStoredMarks(null);
+  return tr.build();
+}
+
+/**
+ * Assigns ONE absolute size to everything the selection touches — the
+ * combobox's write path (ADR-0031), `setSizeDelta`'s counterpart.
+ *
+ * Deliberately NOT implemented as a delta: it never reads the current size,
+ * so a mixed-size selection comes out UNIFORM rather than each stretch
+ * shifting from wherever it already was. That difference is the whole point
+ * of the command — it is what "pick 14pt" means in Word, and what "press A+"
+ * does not mean.
+ *
+ * **Assigning the target to a run that merely INHERITS it still writes an
+ * explicit override** and still produces a real transaction. Word does the
+ * same (choosing a point size writes `w:sz`), but it is worth stating: the
+ * box can read 11 and picking 11 can still change the document.
+ *
+ * @param {import("../state/editor-state.js").EditorState} state
+ * @param {number} targetSz  HALF-POINTS, the model's own unit
+ * @returns {import("../model/transaction.js").Transaction | null}
+ */
+export function setSizeAbsolute(state, targetSz) {
+  const { doc, selection } = state;
+
+  // clampSize is Math.round/min/max, and every one of those passes NaN
+  // straight through — unreachable while `setSizeDelta` was the only caller
+  // (its steps are always ±1), reachable the moment a text field feeds this
+  // one. A NaN here would land in `marks.sz` and from there in `w:sz`.
+  if (!Number.isFinite(targetSz)) {
+    return null;
+  }
+
+  if (isCollapsed(selection)) {
+    // Mirrors setSizeDelta's collapsed branch, minus the one line that
+    // matters: no `resolveSize`, because an absolute target does not care
+    // what the current size is. The two branches are NOT factored together —
+    // they differ in exactly that line, and SZ4's mutation targets it.
+    const current = state.storedMarks ?? marksAt(doc, selection.head);
+    const tr = createTransaction(doc, selection, "format");
+    tr.setStoredMarks(withMarkValue(current, "sz", clampSize(tr, targetSz)));
+    return tr.build();
+  }
+
+  const segments = selectionSizeSegments(doc, selection);
+  if (segments === null || segments.length === 0) {
+    return null;
+  }
+
+  const tr = createTransaction(doc, selection, "format");
+  // ONE clamp for one target — unlike setSizeDelta, which must clamp each
+  // cluster separately because each starts from its own size.
+  const value = clampSize(tr, targetSz);
+
+  tr.step(setSizeStep(segments.map((seg) => ({ from: seg.from, to: seg.to, value }))));
+  if (!tr.changesDoc) {
+    return null;
+  }
+
+  tr.setSelection(selection);
+  tr.setStoredMarks(null);
+  return tr.build();
+}
+
+/**
+ * Parses what a user typed into the point-size box into the model's own
+ * half-point unit. Lives here rather than in `examples/` because it is the
+ * only real logic at that UI boundary, and nothing under `examples/` is
+ * loaded by any Node test (measured — `SESSION-LOG.md` Ek 57).
+ *
+ * Accepts a comma as the decimal separator: the UI is Turkish, and the
+ * numpad's decimal key produces a comma under a Turkish keyboard layout.
+ *
+ * **It does not clamp.** Range enforcement belongs to the command, which has
+ * a transaction to disclose a ceiling hit on; keeping the two apart is what
+ * lets `"5000"` parse cleanly and then be clamped visibly.
+ *
+ * @param {string} text
+ * @returns {number | null}  half-points, or null when there is no number here
+ */
+export function parseSizePoints(text) {
+  const points = Number.parseFloat(text.trim().replace(",", "."));
+  if (!Number.isFinite(points)) {
+    return null;
+  }
+  // Half-points are integers by definition (ST_HpsMeasure is unsigned
+  // decimal), so 11.3pt resolves to the nearest half-point, 11.5.
+  return Math.round(points * 2);
+}