mosage 0.2.0 → 0.8.0

package/src/app/lib/inspector/fiber.ts

@@ -0,0 +1,99 @@
+export type SourceLoc = { line: number; column: number };
+
+type DebugSource = { fileName?: string; lineNumber?: number; columnNumber?: number };
+
+type Fiber = {
+  type?: unknown;
+  return?: Fiber | null;
+  stateNode?: unknown;
+  _debugSource?: DebugSource | null;
+};
+
+const LOC_ATTR = 'data-od-loc';
+
+function fiberOf(el: HTMLElement): Fiber | null {
+  const key = Object.keys(el).find((k) => k.startsWith('__reactFiber$'));
+  return key ? ((el as unknown as Record<string, Fiber>)[key] ?? null) : null;
+}
+
+function locFromAttr(value: string | null): SourceLoc | null {
+  if (!value) return null;
+  const [line, column] = value.split(':').map(Number);
+  if (!Number.isFinite(line) || !Number.isFinite(column)) return null;
+  return { line, column };
+}
+
+function debugLoc(fiber: Fiber): (SourceLoc & { file?: string }) | null {
+  const source = fiber._debugSource;
+  if (!source || typeof source.lineNumber !== 'number' || typeof source.columnNumber !== 'number') {
+    return null;
+  }
+  return { line: source.lineNumber, column: source.columnNumber, file: source.fileName };
+}
+
+/**
+ * Source locations to try for the clicked element, innermost first.
+ *
+ * The DOM only carries a loc for host elements, so a `<td>` rendered by a local
+ * `<Td>text</Td>` helper points at the helper's definition — where the text
+ * isn't. Walking the fiber's `return` chain surfaces the call site, which is
+ * where the author actually wrote the words.
+ *
+ * React's `_debugSource` counts lines against the module *after* the dev
+ * transforms prepend their preamble, so it never matches our loc tags
+ * directly. Rather than hard-coding that offset, calibrate it from any fiber
+ * that carries both values.
+ */
+export function candidateLocs(el: HTMLElement, maxDepth = 12): SourceLoc[] {
+  const domLoc = locFromAttr(el.closest(`[${LOC_ATTR}]`)?.getAttribute(LOC_ATTR) ?? null);
+  const candidates: SourceLoc[] = domLoc ? [domLoc] : [];
+
+  let fiber = fiberOf(el);
+  const chain: Fiber[] = [];
+  for (let depth = 0; fiber && depth < maxDepth; depth++) {
+    chain.push(fiber);
+    fiber = fiber.return ?? null;
+  }
+
+  // Calibrate against a fiber that carries both values — that one is provably
+  // in the document's own source file, which also tells us which file the rest
+  // of the chain has to belong to.
+  let calibration: { line: number; column: number; file?: string } | null = null;
+  for (const node of chain) {
+    const source = debugLoc(node);
+    const host = node.stateNode instanceof HTMLElement ? node.stateNode : null;
+    const tagged = locFromAttr(host?.getAttribute(LOC_ATTR) ?? null);
+    if (source && tagged) {
+      calibration = {
+        line: source.line - tagged.line,
+        column: source.column - tagged.column,
+        file: source.file,
+      };
+      break;
+    }
+  }
+  if (!calibration) return candidates;
+
+  for (const node of chain) {
+    const source = debugLoc(node);
+    if (!source) continue;
+    // Fibers from the framework's own components (FlowPage, PageFrame, …) carry
+    // line numbers from *their* files. Mapping those through the document's
+    // offset lands on unrelated elements, which is how an edit ends up
+    // rewriting the wrong text.
+    if (calibration.file && source.file !== calibration.file) continue;
+    const loc = {
+      line: source.line - calibration.line,
+      column: source.column - calibration.column,
+    };
+    if (loc.line < 1 || loc.column < 0) continue;
+    if (candidates.some((c) => c.line === loc.line && c.column === loc.column)) continue;
+    candidates.push(loc);
+  }
+
+  return candidates;
+}
+
+export function formatLocs(locs: SourceLoc[]): string {
+  return locs.map((loc) => `${loc.line}:${loc.column}`).join(',');
+}

package/src/app/lib/labels.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { defaultVocabulary, onPageParts } from './labels';
+
+describe('onPageParts', () => {
+  it('splits the page suffix around the page number', () => {
+    expect(onPageParts(defaultVocabulary)).toEqual([' (p. ', ')']);
+    expect(onPageParts({ ...defaultVocabulary, onPage: '（第 {page} 頁）' })).toEqual([
+      '（第 ',
+      ' 頁）',
+    ]);
+  });
+
+  /* 沒有 {page} 的後綴要原樣印出，不能把頁碼黏在編號後面變成「Table 15」。 */
+  it('has nothing to split when the suffix names no page', () => {
+    expect(onPageParts({ ...defaultVocabulary, onPage: '' })).toBeNull();
+    expect(onPageParts({ ...defaultVocabulary, onPage: ' (see below)' })).toBeNull();
+  });
+});

package/src/app/lib/labels.ts

@@ -0,0 +1,181 @@
+import { useSyncExternalStore } from 'react';
+import { PAGE_ATTR, PAGE_INDEX_ATTR } from './outline';
+
+export type LabelKind = 'figure' | 'table' | 'footnote';
+
+export type LabelEntry = {
+  /** Author-supplied id for `<Ref to>`, or a generated one. */
+  id: string;
+  kind: LabelKind;
+  /** 1-based, counted per kind across the whole document. */
+  number: number;
+  /** Caption text, for a list of figures. */
+  text: string;
+  /** 1-based page the item sits on. */
+  page: number;
+};
+
+export const LABEL_ATTR = 'data-od-label';
+export const LABEL_ID_ATTR = 'data-od-label-id';
+export const LABEL_TEXT_ATTR = 'data-od-label-text';
+
+/**
+ * The words wrapped around a number. Numbering is structural; what it is
+ * *called* is a document's own business — `圖 3` and `Figure 3` are the same
+ * entry. Set it once in `meta.labels`.
+ */
+export type LabelVocabulary = {
+  figure: string;
+  table: string;
+  /** Heading above a page's footnotes. Empty string renders no heading. */
+  footnotes: string;
+  /** Page suffix for a cross-reference. `{page}` is replaced. */
+  onPage: string;
+};
+
+export const defaultVocabulary: LabelVocabulary = {
+  figure: 'Figure',
+  table: 'Table',
+  footnotes: '',
+  onPage: ' (p. {page})',
+};
+
+export type LabelSnapshot = {
+  entries: LabelEntry[];
+  vocabulary: LabelVocabulary;
+};
+
+const EMPTY: LabelSnapshot = { entries: [], vocabulary: defaultVocabulary };
+
+const KINDS: LabelKind[] = ['figure', 'table', 'footnote'];
+
+function isKind(value: string | null): value is LabelKind {
+  return value !== null && (KINDS as string[]).includes(value);
+}
+
+/**
+ * Walks rendered page frames and numbers everything labelled, in document
+ * order. Numbering is a scan for the same reason the outline is: only the
+ * rendered pages know what ended up where, and a flow section's page breaks are
+ * decided by measurement, not by the author.
+ */
+export function collectLabels(root: ParentNode): LabelEntry[] {
+  const entries: LabelEntry[] = [];
+  const counters: Record<LabelKind, number> = { figure: 0, table: 0, footnote: 0 };
+  const frames = Array.from(root.querySelectorAll<HTMLElement>(`[${PAGE_ATTR}]`));
+
+  frames.forEach((frame, fallbackIndex) => {
+    const declared = Number(frame.getAttribute(PAGE_INDEX_ATTR));
+    const page = (Number.isFinite(declared) ? declared : fallbackIndex) + 1;
+
+    for (const el of Array.from(frame.querySelectorAll<HTMLElement>(`[${LABEL_ATTR}]`))) {
+      const kind = el.getAttribute(LABEL_ATTR);
+      if (!isKind(kind)) continue;
+      const id = el.getAttribute(LABEL_ID_ATTR);
+      if (!id) continue;
+      // A footnote's marker and the note at the foot of the page carry the same
+      // id; the marker is what fixes its position in the sequence.
+      if (entries.some((entry) => entry.id === id)) continue;
+      counters[kind] += 1;
+      entries.push({
+        id,
+        kind,
+        number: counters[kind],
+        text: (el.getAttribute(LABEL_TEXT_ATTR) ?? el.textContent ?? '')
+          .replace(/\s+/g, ' ')
+          .trim(),
+        page,
+      });
+    }
+  });
+
+  return entries;
+}
+
+// Shared through globalThis for the same reason as the outline store: the
+// viewer writes from the source copy of this module while a document's
+// `<Figure>` reads from the published bundle.
+const GLOBAL_KEY = '__mosage_labels_store__';
+type LabelStore = { snapshot: LabelSnapshot; listeners: Set<() => void> };
+type GlobalWithStore = typeof globalThis & { [GLOBAL_KEY]?: LabelStore };
+const g = globalThis as GlobalWithStore;
+if (!g[GLOBAL_KEY]) {
+  g[GLOBAL_KEY] = { snapshot: EMPTY, listeners: new Set() };
+}
+const store = g[GLOBAL_KEY];
+
+function sameEntries(a: LabelEntry[], b: LabelEntry[]): boolean {
+  if (a.length !== b.length) return false;
+  return a.every((entry, i) => {
+    const other = b[i];
+    return (
+      other !== undefined &&
+      entry.id === other.id &&
+      entry.kind === other.kind &&
+      entry.number === other.number &&
+      entry.text === other.text &&
+      entry.page === other.page
+    );
+  });
+}
+
+function sameVocabulary(a: LabelVocabulary, b: LabelVocabulary): boolean {
+  return (
+    a.figure === b.figure &&
+    a.table === b.table &&
+    a.footnotes === b.footnotes &&
+    a.onPage === b.onPage
+  );
+}
+
+export function setLabels(entries: LabelEntry[], vocabulary?: Partial<LabelVocabulary>): void {
+  const next: LabelSnapshot = {
+    entries,
+    vocabulary: { ...defaultVocabulary, ...vocabulary },
+  };
+  if (
+    sameEntries(store.snapshot.entries, next.entries) &&
+    sameVocabulary(store.snapshot.vocabulary, next.vocabulary)
+  ) {
+    return;
+  }
+  store.snapshot = next;
+  for (const listener of store.listeners) listener();
+}
+
+export function getLabels(): LabelSnapshot {
+  return store.snapshot;
+}
+
+function subscribe(listener: () => void): () => void {
+  store.listeners.add(listener);
+  return () => store.listeners.delete(listener);
+}
+
+function useLabelSnapshot(): LabelSnapshot {
+  return useSyncExternalStore(subscribe, getLabels, getLabels);
+}
+
+/** The document's numbered items of one kind, in order. Empty on the first render pass. */
+export function useDocLabels(kind: LabelKind): LabelEntry[] {
+  return useLabelSnapshot().entries.filter((entry) => entry.kind === kind);
+}
+
+/** One numbered item by id, once the scan has run. */
+export function useDocLabel(id: string): LabelEntry | null {
+  return useLabelSnapshot().entries.find((entry) => entry.id === id) ?? null;
+}
+
+export function useLabelVocabulary(): LabelVocabulary {
+  return useLabelSnapshot().vocabulary;
+}
+
+/**
+ * The words either side of the page number in a cross-reference's page suffix,
+ * or null when the suffix names no page — it is then printed as written.
+ */
+export function onPageParts(vocabulary: LabelVocabulary): [before: string, after: string] | null {
+  const at = vocabulary.onPage.indexOf('{page}');
+  if (at < 0) return null;
+  return [vocabulary.onPage.slice(0, at), vocabulary.onPage.slice(at + '{page}'.length)];
+}

package/src/app/lib/outline.ts

@@ -0,0 +1,118 @@
+import { useSyncExternalStore } from 'react';
+
+export type OutlineEntry = {
+  id: string;
+  text: string;
+  level: number;
+  /** 1-based page the heading sits on. */
+  page: number;
+};
+
+export const HEADING_SELECTOR = 'h1, h2, h3, [data-od-heading]';
+
+export const PAGE_ATTR = 'data-od-page';
+export const PAGE_INDEX_ATTR = 'data-od-page-index';
+/** A contents list; headings inside one are never part of the outline. */
+export const TOC_ATTR = 'data-od-toc';
+
+export function levelOf(el: Element): number {
+  const declared = el.getAttribute('data-od-level');
+  if (declared) {
+    const n = Number(declared);
+    if (Number.isFinite(n)) return Math.min(3, Math.max(1, Math.round(n)));
+  }
+  const tag = el.tagName.toLowerCase();
+  if (tag === 'h1') return 1;
+  if (tag === 'h2') return 2;
+  if (tag === 'h3') return 3;
+  return 2;
+}
+
+function textOf(el: Element): string {
+  const labelled = el.getAttribute('data-od-heading');
+  if (labelled && labelled !== 'true' && labelled.trim() !== '') return labelled.trim();
+  return (el.textContent ?? '').replace(/\s+/g, ' ').trim();
+}
+
+/** The level a heading has in the outline, or null when it is kept out of it. */
+export function outlineLevelOf(el: Element): number | null {
+  if (el.closest(`[${TOC_ATTR}]`)) return null;
+  if (el.getAttribute('data-od-outline') === 'skip') return null;
+  return levelOf(el);
+}
+
+/**
+ * Walks rendered page frames and returns their headings in document order.
+ * Headings inside a rendered table of contents are skipped so a TOC never
+ * lists itself, and every collected heading gets a stable `id` so the sidebar
+ * and in-document TOC can anchor to it.
+ */
+export function collectOutline(root: ParentNode): OutlineEntry[] {
+  const entries: OutlineEntry[] = [];
+  const frames = Array.from(root.querySelectorAll<HTMLElement>(`[${PAGE_ATTR}]`));
+  frames.forEach((frame, fallbackIndex) => {
+    const declared = Number(frame.getAttribute(PAGE_INDEX_ATTR));
+    const page = (Number.isFinite(declared) ? declared : fallbackIndex) + 1;
+    const headings = Array.from(frame.querySelectorAll<HTMLElement>(HEADING_SELECTOR));
+    for (const el of headings) {
+      const level = outlineLevelOf(el);
+      if (level === null) continue;
+      const text = textOf(el);
+      if (!text) continue;
+      const id = el.id || `od-h-${entries.length + 1}`;
+      if (!el.id) el.id = id;
+      entries.push({ id, text, level, page });
+    }
+  });
+  return entries;
+}
+
+// Shared through globalThis for the same reason as the page context: the
+// viewer writes the outline from the source copy of this module, while a
+// document's `<TableOfContents>` reads it from the published bundle.
+const GLOBAL_KEY = '__mosage_outline_store__';
+type OutlineStore = { snapshot: OutlineEntry[]; listeners: Set<() => void> };
+type GlobalWithStore = typeof globalThis & { [GLOBAL_KEY]?: OutlineStore };
+const g = globalThis as GlobalWithStore;
+if (!g[GLOBAL_KEY]) {
+  g[GLOBAL_KEY] = { snapshot: [], listeners: new Set() };
+}
+const store = g[GLOBAL_KEY];
+
+function sameOutline(a: OutlineEntry[], b: OutlineEntry[]): boolean {
+  if (a.length !== b.length) return false;
+  return a.every((entry, i) => {
+    const other = b[i];
+    return (
+      other !== undefined &&
+      entry.id === other.id &&
+      entry.text === other.text &&
+      entry.level === other.level &&
+      entry.page === other.page
+    );
+  });
+}
+
+export function setOutline(entries: OutlineEntry[]): void {
+  if (sameOutline(store.snapshot, entries)) return;
+  store.snapshot = entries;
+  for (const listener of store.listeners) listener();
+}
+
+export function getOutline(): OutlineEntry[] {
+  return store.snapshot;
+}
+
+function subscribe(listener: () => void): () => void {
+  store.listeners.add(listener);
+  return () => store.listeners.delete(listener);
+}
+
+/**
+ * The document's headings, filled in after the pages render. Empty on the first
+ * pass — a `<TableOfContents>` renders its rows on the second, once the scan
+ * has run.
+ */
+export function useDocOutline(): OutlineEntry[] {
+  return useSyncExternalStore(subscribe, getOutline, getOutline);
+}

package/src/app/lib/page-context.tsx

@@ -0,0 +1,43 @@
+import { type Context, createContext, type ReactNode, useContext, useMemo } from 'react';
+import { FootnoteCollector } from '../components/footnote';
+
+type PageContextValue = { index: number; total: number };
+
+// Stored on globalThis so the dev (src) and published (dist) copies of this
+// module share one context instance — a document imports `mosage`
+// (dist) while the viewer imports the source, so without this the provider
+// writes to one context and the hook reads from another.
+const GLOBAL_KEY = '__mosage_page_context__';
+type GlobalWithCtx = typeof globalThis & {
+  [GLOBAL_KEY]?: Context<PageContextValue | null>;
+};
+const g = globalThis as GlobalWithCtx;
+if (!g[GLOBAL_KEY]) {
+  g[GLOBAL_KEY] = createContext<PageContextValue | null>(null);
+}
+const PageContext = g[GLOBAL_KEY];
+
+export function DocPageProvider({
+  index,
+  total,
+  children,
+}: PageContextValue & { children?: ReactNode }) {
+  const value = useMemo(() => ({ index, total }), [index, total]);
+  return (
+    <PageContext.Provider value={value}>
+      <FootnoteCollector>{children}</FootnoteCollector>
+    </PageContext.Provider>
+  );
+}
+
+/** 1-based page number of the page currently rendering. `0` outside a page. */
+export function useDocPageNumber(): number {
+  const ctx = useContext(PageContext);
+  return ctx ? ctx.index + 1 : 0;
+}
+
+/** Total page count of the document being rendered. `0` outside a page. */
+export function useDocPageCount(): number {
+  const ctx = useContext(PageContext);
+  return ctx ? ctx.total : 0;
+}

package/src/app/lib/page-range.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Page ranges, where off-by-one lives.
+ *
+ * The reader types "1" and means the first page; the array wants index 0. Every
+ * assertion here is about that seam, plus the two answers that must stay
+ * distinct: "nothing you typed names a page" and "you selected no pages". Only
+ * one of them should ever start a download, and neither should download
+ * everything by accident.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { describeSelection, parseRange, resolveSelection } from './page-range';
+
+describe('parseRange', () => {
+  it('reads single pages, one-based', () => {
+    expect(parseRange('1', 5)).toEqual([0]);
+    expect(parseRange('3', 5)).toEqual([2]);
+  });
+
+  it('reads spans, inclusive at both ends', () => {
+    expect(parseRange('1-3', 5)).toEqual([0, 1, 2]);
+    expect(parseRange('4-5', 5)).toEqual([3, 4]);
+  });
+
+  it('reads a mixed list, sorted and deduplicated', () => {
+    expect(parseRange('5,1,2-3,1', 9)).toEqual([0, 1, 2, 4]);
+  });
+
+  /* A range typed backwards is a range, not a mistake worth refusing. */
+  it('accepts a span written the wrong way round', () => {
+    expect(parseRange('5-2', 9)).toEqual([1, 2, 3, 4]);
+  });
+
+  /* 中文鍵盤打出來的全形數字和破折號，使用者不會察覺自己打的是全形。 */
+  it('accepts full-width digits and dashes', () => {
+    expect(parseRange('１-３', 5)).toEqual([0, 1, 2]);
+    expect(parseRange('２，４', 5)).toEqual([1, 3]);
+  });
+
+  it('clips to the document rather than inventing pages', () => {
+    expect(parseRange('3-99', 5)).toEqual([2, 3, 4]);
+    expect(parseRange('0-2', 5)).toEqual([0, 1]);
+  });
+
+  /*
+   * The important negative: nothing usable must be null, never an empty array.
+   * An empty array flowing on would start a download of no pages.
+   */
+  it('returns null when nothing names a real page', () => {
+    expect(parseRange('', 5)).toBeNull();
+    expect(parseRange('   ', 5)).toBeNull();
+    expect(parseRange('abc', 5)).toBeNull();
+    expect(parseRange('9', 5)).toBeNull();
+    expect(parseRange('-', 5)).toBeNull();
+  });
+});
+
+describe('resolveSelection', () => {
+  it('all covers the document', () => {
+    expect(resolveSelection({ kind: 'all' }, 3, 2)).toEqual([0, 1, 2]);
+  });
+
+  it('current is the page being read, one-based in and zero-based out', () => {
+    expect(resolveSelection({ kind: 'current' }, 5, 1)).toEqual([0]);
+    expect(resolveSelection({ kind: 'current' }, 5, 4)).toEqual([3]);
+  });
+
+  /* currentPage can lag the document while it reflows; it must not index past. */
+  it('clamps a current page outside the document', () => {
+    expect(resolveSelection({ kind: 'current' }, 3, 99)).toEqual([2]);
+    expect(resolveSelection({ kind: 'current' }, 3, 0)).toEqual([0]);
+  });
+
+  it('has nothing to give for an empty document', () => {
+    expect(resolveSelection({ kind: 'all' }, 0, 1)).toBeNull();
+  });
+});
+
+describe('describeSelection', () => {
+  it('counts what the button is about to do', () => {
+    expect(describeSelection({ kind: 'all' }, 4, 1)).toEqual({ count: 4, valid: true });
+    expect(describeSelection({ kind: 'current' }, 4, 2)).toEqual({ count: 1, valid: true });
+    expect(describeSelection({ kind: 'custom', text: '2-3' }, 4, 1)).toEqual({
+      count: 2,
+      valid: true,
+    });
+  });
+
+  it('reports an unreadable range as invalid, not as zero pages', () => {
+    expect(describeSelection({ kind: 'custom', text: 'nope' }, 4, 1)).toEqual({
+      count: 0,
+      valid: false,
+    });
+  });
+});

package/src/app/lib/page-range.ts

@@ -0,0 +1,90 @@
+/**
+ * Which pages a download covers.
+ *
+ * The custom field takes what a print dialog takes — `2`, `1-3`, `2,5,7-9` —
+ * because that is the notation people already have in their fingers. Everything
+ * here is 1-based on the way in and 0-based on the way out, which is where this
+ * kind of code usually goes wrong: the reader says "page 1" and the array
+ * wants index 0.
+ */
+
+export type PageSelection =
+  | { kind: 'all' }
+  | { kind: 'current' }
+  | { kind: 'custom'; text: string };
+
+/**
+ * Zero-based indices, ascending, no duplicates.
+ *
+ * An unparseable or empty custom range returns null rather than an empty list:
+ * "I could not read that" and "you asked for no pages" are different answers,
+ * and only one of them should be allowed to start a download.
+ */
+export function resolveSelection(
+  selection: PageSelection,
+  total: number,
+  currentPage: number,
+): number[] | null {
+  if (total <= 0) return null;
+  if (selection.kind === 'all') return Array.from({ length: total }, (_, i) => i);
+  if (selection.kind === 'current') {
+    const index = clamp(currentPage, 1, total) - 1;
+    return [index];
+  }
+  return parseRange(selection.text, total);
+}
+
+/** `2,5,7-9` → [1,4,6,7,8]. Null when nothing in the text names a real page. */
+export function parseRange(text: string, total: number): number[] | null {
+  if (text.trim() === '') return null;
+
+  const wanted = new Set<number>();
+  let sawSomething = false;
+
+  for (const chunk of text.split(/[,，\s]+/)) {
+    if (chunk === '') continue;
+    /* Full-width digits and dashes: a Chinese keyboard produces them without
+       the typist noticing, and rejecting them reads as the field being broken. */
+    const plain = chunk
+      .replace(/[０-９]/g, (d) => String(d.charCodeAt(0) - 0xff10))
+      .replace(/[–—ー－]/g, '-');
+
+    const span = /^(\d+)-(\d+)$/.exec(plain);
+    if (span) {
+      const from = Number(span[1]);
+      const to = Number(span[2]);
+      if (!Number.isFinite(from) || !Number.isFinite(to)) continue;
+      /* `5-2` is a range someone typed backwards, not an empty one. */
+      const [lo, hi] = from <= to ? [from, to] : [to, from];
+      for (let page = Math.max(1, lo); page <= Math.min(total, hi); page++) {
+        wanted.add(page - 1);
+        sawSomething = true;
+      }
+      continue;
+    }
+
+    if (/^\d+$/.test(plain)) {
+      const page = Number(plain);
+      if (page >= 1 && page <= total) {
+        wanted.add(page - 1);
+        sawSomething = true;
+      }
+    }
+  }
+
+  if (!sawSomething || wanted.size === 0) return null;
+  return [...wanted].sort((a, b) => a - b);
+}
+
+export function describeSelection(
+  selection: PageSelection,
+  total: number,
+  currentPage: number,
+): { count: number; valid: boolean } {
+  const pages = resolveSelection(selection, total, currentPage);
+  return { count: pages?.length ?? 0, valid: pages !== null };
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}