@seamless-co/pagemark 0.0.0-stage → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (150) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +25 -2
  3. package/behaviours/behaviour.d.ts +43 -0
  4. package/behaviours/behaviour.js +84 -0
  5. package/behaviours/comparison.d.ts +62 -0
  6. package/behaviours/comparison.js +129 -0
  7. package/behaviours/document-viewer.d.ts +9 -0
  8. package/behaviours/document-viewer.js +9 -0
  9. package/behaviours/hidden.d.ts +24 -0
  10. package/behaviours/hidden.js +38 -0
  11. package/behaviours/hover.d.ts +34 -0
  12. package/behaviours/hover.js +49 -0
  13. package/behaviours/index.d.ts +24 -0
  14. package/behaviours/index.js +14 -0
  15. package/behaviours/linked-viewers.d.ts +14 -0
  16. package/behaviours/linked-viewers.js +25 -0
  17. package/behaviours/links.d.ts +4 -0
  18. package/behaviours/links.js +4 -0
  19. package/behaviours/marks.d.ts +64 -0
  20. package/behaviours/marks.js +33 -0
  21. package/behaviours/quotes.d.ts +7 -0
  22. package/behaviours/quotes.js +9 -0
  23. package/behaviours/region.d.ts +27 -0
  24. package/behaviours/region.js +40 -0
  25. package/behaviours/search.d.ts +38 -0
  26. package/behaviours/search.js +63 -0
  27. package/behaviours/selection.d.ts +30 -0
  28. package/behaviours/selection.js +41 -0
  29. package/behaviours/text.d.ts +8 -0
  30. package/behaviours/text.js +24 -0
  31. package/behaviours/viewer-state.d.ts +36 -0
  32. package/behaviours/viewer-state.js +58 -0
  33. package/browser/blob-pieces.d.ts +9 -0
  34. package/browser/blob-pieces.js +50 -0
  35. package/browser/browser-source.d.ts +25 -0
  36. package/browser/browser-source.js +62 -0
  37. package/browser/index.d.ts +2 -0
  38. package/browser/index.js +1 -0
  39. package/browser/local-pdf.d.ts +27 -0
  40. package/browser/local-pdf.js +61 -0
  41. package/browser/worker-engine.d.ts +21 -0
  42. package/browser/worker-engine.js +1 -0
  43. package/browser/worker.d.ts +1 -0
  44. package/browser/worker.js +51 -0
  45. package/core/compare.d.ts +55 -0
  46. package/core/compare.js +350 -0
  47. package/core/find.d.ts +12 -0
  48. package/core/find.js +177 -0
  49. package/core/hidden.d.ts +12 -0
  50. package/core/hidden.js +26 -0
  51. package/core/index.d.ts +11 -0
  52. package/core/index.js +6 -0
  53. package/core/links.d.ts +7 -0
  54. package/core/links.js +19 -0
  55. package/core/locate.d.ts +21 -0
  56. package/core/locate.js +140 -0
  57. package/core/paragraphs.d.ts +37 -0
  58. package/core/paragraphs.js +141 -0
  59. package/core/types.d.ts +89 -0
  60. package/core/types.js +1 -0
  61. package/document/document.d.ts +83 -0
  62. package/document/document.js +215 -0
  63. package/document/handover-source.d.ts +18 -0
  64. package/document/handover-source.js +39 -0
  65. package/document/index.d.ts +10 -0
  66. package/document/index.js +5 -0
  67. package/document/reading-source.d.ts +7 -0
  68. package/document/reading-source.js +16 -0
  69. package/document/server-source.d.ts +10 -0
  70. package/document/server-source.js +23 -0
  71. package/document/source.d.ts +21 -0
  72. package/document/source.js +1 -0
  73. package/document/split-source.d.ts +9 -0
  74. package/document/split-source.js +25 -0
  75. package/document/store.d.ts +12 -0
  76. package/document/store.js +21 -0
  77. package/engine/engine-thread.d.ts +10 -0
  78. package/engine/engine-thread.js +1 -0
  79. package/engine/index.d.ts +2 -0
  80. package/engine/index.js +1 -0
  81. package/engine/pdfium.d.ts +16 -0
  82. package/engine/pdfium.js +222 -0
  83. package/engine/remote.d.ts +51 -0
  84. package/engine/remote.js +109 -0
  85. package/package.json +65 -4
  86. package/react/hooks.d.ts +128 -0
  87. package/react/hooks.js +129 -0
  88. package/react/index.d.ts +3 -0
  89. package/react/index.js +2 -0
  90. package/react/viewer.d.ts +48 -0
  91. package/react/viewer.js +127 -0
  92. package/reader/assemble.d.ts +4 -0
  93. package/reader/assemble.js +29 -0
  94. package/reader/index.d.ts +7 -0
  95. package/reader/index.js +5 -0
  96. package/reader/layer-page.d.ts +30 -0
  97. package/reader/layer-page.js +40 -0
  98. package/reader/layer-words.d.ts +4 -0
  99. package/reader/layer-words.js +102 -0
  100. package/reader/letter-edges.d.ts +13 -0
  101. package/reader/letter-edges.js +60 -0
  102. package/reader/links.d.ts +7 -0
  103. package/reader/links.js +22 -0
  104. package/reader/seams.d.ts +92 -0
  105. package/reader/seams.js +3 -0
  106. package/reader/seen.d.ts +16 -0
  107. package/reader/seen.js +67 -0
  108. package/reader/trust.d.ts +9 -0
  109. package/reader/trust.js +34 -0
  110. package/viewer/attachments.d.ts +11 -0
  111. package/viewer/attachments.js +104 -0
  112. package/viewer/dom.d.ts +14 -0
  113. package/viewer/dom.js +38 -0
  114. package/viewer/events.d.ts +17 -0
  115. package/viewer/events.js +20 -0
  116. package/viewer/index.d.ts +17 -0
  117. package/viewer/index.js +8 -0
  118. package/viewer/links.d.ts +16 -0
  119. package/viewer/links.js +59 -0
  120. package/viewer/marks.d.ts +24 -0
  121. package/viewer/marks.js +171 -0
  122. package/viewer/page-layers.d.ts +13 -0
  123. package/viewer/page-layers.js +33 -0
  124. package/viewer/pictures.d.ts +24 -0
  125. package/viewer/pictures.js +293 -0
  126. package/viewer/pointer.d.ts +21 -0
  127. package/viewer/pointer.js +244 -0
  128. package/viewer/stage.d.ts +21 -0
  129. package/viewer/stage.js +31 -0
  130. package/viewer/text-between.d.ts +13 -0
  131. package/viewer/text-between.js +28 -0
  132. package/viewer/text.d.ts +20 -0
  133. package/viewer/text.js +180 -0
  134. package/viewer/tile-grid.d.ts +20 -0
  135. package/viewer/tile-grid.js +36 -0
  136. package/viewer/tiles.d.ts +15 -0
  137. package/viewer/tiles.js +190 -0
  138. package/viewer/turn.d.ts +18 -0
  139. package/viewer/turn.js +40 -0
  140. package/viewer/types.d.ts +238 -0
  141. package/viewer/types.js +1 -0
  142. package/viewer/view-over.d.ts +21 -0
  143. package/viewer/view-over.js +191 -0
  144. package/viewer/view.d.ts +59 -0
  145. package/viewer/view.js +1 -0
  146. package/viewer/viewer.css +301 -0
  147. package/viewer/viewer.d.ts +11 -0
  148. package/viewer/viewer.js +104 -0
  149. package/viewer/viewport.d.ts +37 -0
  150. package/viewer/viewport.js +429 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Seamless Hire
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,26 @@
1
- # Temporary Holding Version
1
+ # @seamless-co/pagemark
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Locates text on PDF pages and marks it, in the browser. The [pagemark repository](https://github.com/seamless-co/pagemark)
4
+ says what each part does and how to use it.
5
+
6
+ ```sh
7
+ npm install pagemark@npm:@seamless-co/pagemark
8
+ ```
9
+
10
+ That installs it under the name `pagemark`, which the imports below use.
11
+
12
+ ```ts
13
+ import { findQuote } from "pagemark/core";
14
+ import { browserSource } from "pagemark/browser";
15
+ import { PagemarkViewer, useDocument } from "pagemark/react";
16
+ import "pagemark/viewer.css";
17
+ ```
18
+
19
+ Parts: `pagemark/core`, `pagemark/document`, `pagemark/browser`, `pagemark/viewer`, `pagemark/behaviours`,
20
+ `pagemark/react`, and `pagemark/reader` and `pagemark/engine`, which the browser part is built on.
21
+
22
+ `browserSource` finds the engine's file, `pdfium.wasm`, beside the engine's code, where a bundler that follows
23
+ `new URL(…, import.meta.url)` copies it. With another bundler, serve the file from the `@hyzyla/pdfium` package, at
24
+ the exact version this package depends on, and pass its address as `wasmUrl`.
25
+
26
+ MIT licence. Refer to `LICENSE`.
@@ -0,0 +1,43 @@
1
+ import type { PageReading } from "../core/index.js";
2
+ import type { PagemarkDocument, Readable } from "../document/index.js";
3
+ /**
4
+ * NOTE: what a screen does with a document, as one object: it holds its own state, says when the state changes, and
5
+ * takes commands. A framework binds to any of them the same way, through `get` and `subscribe`, so a behaviour is
6
+ * written once and its state lives here and not in a component.
7
+ * NOTE: it watches its document only while something is listening to it, and catches up when asked for its state.
8
+ * So it needs no closing: one that nobody listens to holds on to nothing.
9
+ * NOTE: it is made for one document, or for none yet, and a comparison for two. A new document gets a new
10
+ * behaviour, which is how its state starts over.
11
+ * NOTE: `Inputs` is what a caller hands it from outside, as a search is handed its quote. Most take none.
12
+ * INVARIANT: every member that is a function works when handed on by itself, as `search.next`.
13
+ */
14
+ export declare abstract class Behaviour<State, Inputs = void> implements Readable<State> {
15
+ #private;
16
+ /** NOTE: the documents it was made for, in the order given: one for most behaviours, two for a comparison. */
17
+ protected readonly documents: ReadonlyArray<PagemarkDocument | null>;
18
+ constructor(document: PagemarkDocument | null | ReadonlyArray<PagemarkDocument | null>, initial: State);
19
+ readonly get: () => State;
20
+ readonly subscribe: (listener: () => void) => (() => void);
21
+ /**
22
+ * NOTE: the state this behaviour would have for `inputs`, with nothing changed and nobody told. A binding that is
23
+ * handed inputs draws this at once and sets them after, so a screen never shows the state of inputs it no longer
24
+ * has. A behaviour that takes none says its own state.
25
+ * INVARIANT: asked again with nothing changed, it is the same object, and `set` takes that object for the state. A
26
+ * binding compares states by identity, and would draw again for an equal one.
27
+ */
28
+ readonly stateFor: (inputs: Inputs) => State;
29
+ /** NOTE: takes inputs from outside. A behaviour that takes none has nothing to do. */
30
+ readonly set: (inputs: Inputs) => void;
31
+ /** NOTE: the document, for a behaviour made for one: the first it was given. */
32
+ protected get document(): PagemarkDocument | null;
33
+ /** NOTE: the document's pages as they are now, with whatever words have arrived; none with no document. */
34
+ protected get pages(): ReadonlyArray<PageReading>;
35
+ /** NOTE: whether every word that will arrive is here, in every document. With no document none will, so there is nothing to wait for. */
36
+ protected get isComplete(): boolean;
37
+ /** NOTE: called when someone starts listening, for a behaviour that has something to fetch once it is being shown. */
38
+ protected watched(): void;
39
+ /** NOTE: takes a new state and tells whoever listens. The same state again tells nobody. */
40
+ protected change(next: State): void;
41
+ /** NOTE: what the state becomes when a document's words have changed under it. */
42
+ protected abstract follow(state: State): State;
43
+ }
@@ -0,0 +1,84 @@
1
+ const NO_PAGES = [];
2
+ /**
3
+ * NOTE: what a screen does with a document, as one object: it holds its own state, says when the state changes, and
4
+ * takes commands. A framework binds to any of them the same way, through `get` and `subscribe`, so a behaviour is
5
+ * written once and its state lives here and not in a component.
6
+ * NOTE: it watches its document only while something is listening to it, and catches up when asked for its state.
7
+ * So it needs no closing: one that nobody listens to holds on to nothing.
8
+ * NOTE: it is made for one document, or for none yet, and a comparison for two. A new document gets a new
9
+ * behaviour, which is how its state starts over.
10
+ * NOTE: `Inputs` is what a caller hands it from outside, as a search is handed its quote. Most take none.
11
+ * INVARIANT: every member that is a function works when handed on by itself, as `search.next`.
12
+ */
13
+ export class Behaviour {
14
+ /** NOTE: the documents it was made for, in the order given: one for most behaviours, two for a comparison. */
15
+ documents;
16
+ #listeners = new Set();
17
+ #state;
18
+ #followed = null;
19
+ #unwatch = null;
20
+ constructor(document, initial) {
21
+ this.documents = Array.isArray(document) ? document : [document];
22
+ this.#state = initial;
23
+ }
24
+ get = () => {
25
+ this.#follow();
26
+ return this.#state;
27
+ };
28
+ subscribe = (listener) => {
29
+ this.#listeners.add(listener);
30
+ if (!this.#unwatch) {
31
+ this.#unwatch = this.documents.flatMap((document) => (document ? [document.subscribe(() => this.#follow())] : []));
32
+ this.watched();
33
+ }
34
+ return () => {
35
+ this.#listeners.delete(listener);
36
+ if (this.#listeners.size > 0)
37
+ return;
38
+ for (const unwatch of this.#unwatch ?? [])
39
+ unwatch();
40
+ this.#unwatch = null;
41
+ };
42
+ };
43
+ /**
44
+ * NOTE: the state this behaviour would have for `inputs`, with nothing changed and nobody told. A binding that is
45
+ * handed inputs draws this at once and sets them after, so a screen never shows the state of inputs it no longer
46
+ * has. A behaviour that takes none says its own state.
47
+ * INVARIANT: asked again with nothing changed, it is the same object, and `set` takes that object for the state. A
48
+ * binding compares states by identity, and would draw again for an equal one.
49
+ */
50
+ stateFor = () => this.get();
51
+ /** NOTE: takes inputs from outside. A behaviour that takes none has nothing to do. */
52
+ set = () => undefined;
53
+ /** NOTE: the document, for a behaviour made for one: the first it was given. */
54
+ get document() {
55
+ return this.documents[0] ?? null;
56
+ }
57
+ /** NOTE: the document's pages as they are now, with whatever words have arrived; none with no document. */
58
+ get pages() {
59
+ return this.document?.pages ?? NO_PAGES;
60
+ }
61
+ /** NOTE: whether every word that will arrive is here, in every document. With no document none will, so there is nothing to wait for. */
62
+ get isComplete() {
63
+ return this.documents.every((document) => document?.isComplete ?? true);
64
+ }
65
+ /** NOTE: called when someone starts listening, for a behaviour that has something to fetch once it is being shown. */
66
+ watched() { }
67
+ /** NOTE: takes a new state and tells whoever listens. The same state again tells nobody. */
68
+ change(next) {
69
+ if (next === this.#state)
70
+ return;
71
+ this.#state = next;
72
+ for (const listener of [...this.#listeners])
73
+ listener();
74
+ }
75
+ #follow() {
76
+ const pages = this.documents.map((document) => document?.pages ?? NO_PAGES);
77
+ const { isComplete } = this;
78
+ const known = this.#followed;
79
+ if (known && known.isComplete === isComplete && known.pages.every((each, order) => each === pages[order]))
80
+ return;
81
+ this.#followed = { pages, isComplete };
82
+ this.change(this.follow(this.#state));
83
+ }
84
+ }
@@ -0,0 +1,62 @@
1
+ import { type Change, type PageReading, type ParagraphChange } from "../core/index.js";
2
+ import type { PagemarkDocument } from "../document/index.js";
3
+ import { Behaviour } from "./behaviour.js";
4
+ import { type ChangeMark, type Marked, type ParagraphMark } from "./marks.js";
5
+ export type Side = "before" | "after";
6
+ /** NOTE: one mark per run of words a change touches on one side, carrying the change. Words that only moved have a tone of their own on both sides. */
7
+ export declare function comparisonMarks(changes: ReadonlyArray<Change>, side: Side): ChangeMark[];
8
+ /** NOTE: what to say beside a change on one side: what it became, or what it was. */
9
+ export declare function changeNote(change: Change, side: Side): string;
10
+ export declare function changeSummary(change: Change): string;
11
+ /**
12
+ * NOTE: one mark for each page a paragraph change touches on one side, carrying the change, so a change is lit whole
13
+ * by focusing every mark of its order. A side where no word differs still has a mark, in the tone `place` or
14
+ * `moved`, since that is where the other side's change belongs.
15
+ */
16
+ export declare function paragraphMarks(changes: ReadonlyArray<ParagraphChange>, side: Side): ParagraphMark[];
17
+ /** NOTE: what to say beside a paragraph change on one side: its wording on the other side, or what became of it. */
18
+ export declare function paragraphNote(change: ParagraphChange, side: Side): string;
19
+ export type ComparisonState<Changed, Mark> = {
20
+ changes: Changed[];
21
+ marksBefore: Mark[];
22
+ marksAfter: Mark[];
23
+ /** NOTE: which change is in hand, counted from 0, or -1 when there is none. */
24
+ focused: number;
25
+ /** NOTE: the ids of the marks the change in hand has on each side: what to hand that side's viewer as its focus. */
26
+ focusedBefore: string[];
27
+ focusedAfter: string[];
28
+ /** NOTE: true while either version's words have not all arrived, so "no differences" is not yet the answer. */
29
+ isPartial: boolean;
30
+ };
31
+ /**
32
+ * NOTE: what changed between two versions of a document, as one object made from the two: the changes, each side's
33
+ * marks, and the change in hand, with the commands that step through them.
34
+ * NOTE: it tells of no change until every word of both versions is here, since a page still to come would be told as
35
+ * a page taken out. It fetches what is missing once someone listens, and `isPartial` says while it waits.
36
+ * NOTE: how changes are told is left to the comparison made for it: `WordComparison` by runs of words,
37
+ * `ParagraphComparison` by paragraph.
38
+ */
39
+ export declare abstract class Comparison<Changed, Mark extends Marked<{
40
+ order: number;
41
+ }>> extends Behaviour<ComparisonState<Changed, Mark>> {
42
+ #private;
43
+ constructor(before: PagemarkDocument | null, after: PagemarkDocument | null);
44
+ readonly next: () => void;
45
+ readonly previous: () => void;
46
+ /** NOTE: takes one change in hand, held inside the range of what changed. Nothing is compared again. */
47
+ readonly focus: (index: number) => void;
48
+ protected abstract compare(before: ReadonlyArray<PageReading>, after: ReadonlyArray<PageReading>): Changed[];
49
+ protected abstract marks(changes: ReadonlyArray<Changed>, side: Side): Mark[];
50
+ protected watched(): void;
51
+ protected follow(state: ComparisonState<Changed, Mark>): ComparisonState<Changed, Mark>;
52
+ }
53
+ /** NOTE: tells each run of words that differs as its own change. */
54
+ export declare class WordComparison extends Comparison<Change, ChangeMark> {
55
+ protected compare(before: ReadonlyArray<PageReading>, after: ReadonlyArray<PageReading>): Change[];
56
+ protected marks(changes: ReadonlyArray<Change>, side: Side): ChangeMark[];
57
+ }
58
+ /** NOTE: tells changes by paragraph, which reads best as a list. */
59
+ export declare class ParagraphComparison extends Comparison<ParagraphChange, ParagraphMark> {
60
+ protected compare(before: ReadonlyArray<PageReading>, after: ReadonlyArray<PageReading>): ParagraphChange[];
61
+ protected marks(changes: ReadonlyArray<ParagraphChange>, side: Side): ParagraphMark[];
62
+ }
@@ -0,0 +1,129 @@
1
+ import { compareParagraphs, compareReadings } from "../core/index.js";
2
+ import { Behaviour } from "./behaviour.js";
3
+ import { markIds } from "./marks.js";
4
+ import { stepFocus } from "./search.js";
5
+ /** NOTE: one mark per run of words a change touches on one side, carrying the change. Words that only moved have a tone of their own on both sides. */
6
+ export function comparisonMarks(changes, side) {
7
+ return changes.flatMap((change, order) => change[side].map((run, span) => ({
8
+ id: `change-${order}-${span}`,
9
+ page: run.page,
10
+ rects: run.rects,
11
+ tone: change.kind === "moved" ? "moved" : side === "before" ? "removed" : "added",
12
+ ...(span === 0 ? { label: `Change ${order + 1} of ${changes.length}. ${changeNote(change, side)}` } : {}),
13
+ of: { kind: "change", order, span, side, change },
14
+ })));
15
+ }
16
+ /** NOTE: what to say beside a change on one side: what it became, or what it was. */
17
+ export function changeNote(change, side) {
18
+ if (change.kind === "moved")
19
+ return side === "before" ? "Moved from here" : "Moved here";
20
+ if (side === "before")
21
+ return change.afterText ? `Now: ${change.afterText}` : "Removed";
22
+ return change.beforeText ? `Was: ${change.beforeText}` : "Added";
23
+ }
24
+ export function changeSummary(change) {
25
+ if (change.kind === "moved")
26
+ return `↕ ${change.afterText}`;
27
+ if (change.kind === "added")
28
+ return `+ ${change.afterText}`;
29
+ if (change.kind === "removed")
30
+ return `− ${change.beforeText}`;
31
+ return `${change.beforeText} → ${change.afterText}`;
32
+ }
33
+ /**
34
+ * NOTE: where a paragraph change shows on one side, page by page: the words that differ, or, on a side where none do
35
+ * (words were only added on the other side, or the paragraph only moved), the paragraph itself.
36
+ */
37
+ function placesOf(change, side) {
38
+ const { spans, paragraphs } = change[side];
39
+ const tone = change.kind === "moved" ? "moved" : spans.length === 0 ? "place" : side === "before" ? "removed" : "added";
40
+ const pages = new Map();
41
+ for (const { page, rects } of spans.length > 0 ? spans : paragraphs)
42
+ pages.set(page, [...(pages.get(page) ?? []), ...rects]);
43
+ return [...pages].map(([page, rects]) => ({ page, rects, tone }));
44
+ }
45
+ /**
46
+ * NOTE: one mark for each page a paragraph change touches on one side, carrying the change, so a change is lit whole
47
+ * by focusing every mark of its order. A side where no word differs still has a mark, in the tone `place` or
48
+ * `moved`, since that is where the other side's change belongs.
49
+ */
50
+ export function paragraphMarks(changes, side) {
51
+ return changes.flatMap((change, order) => placesOf(change, side).map(({ page, rects, tone }, place) => ({
52
+ id: `paragraph-${order}-${page}`,
53
+ page,
54
+ rects,
55
+ tone,
56
+ ...(place === 0 ? { label: `Change ${order + 1} of ${changes.length}. ${paragraphNote(change, side)}` } : {}),
57
+ of: { kind: "paragraph", order, side, change },
58
+ })));
59
+ }
60
+ /** NOTE: what to say beside a paragraph change on one side: its wording on the other side, or what became of it. */
61
+ export function paragraphNote(change, side) {
62
+ if (change.kind === "moved")
63
+ return side === "before" ? "Moved from here" : "Moved here";
64
+ if (side === "before")
65
+ return change.after.text ? `Now: ${change.after.text}` : "Removed";
66
+ return change.before.text ? `Was: ${change.before.text}` : "Added";
67
+ }
68
+ const NOTHING = { changes: [], marksBefore: [], marksAfter: [], focused: -1, focusedBefore: [], focusedAfter: [], isPartial: false };
69
+ const WAITING = { ...NOTHING, isPartial: true };
70
+ /**
71
+ * NOTE: what changed between two versions of a document, as one object made from the two: the changes, each side's
72
+ * marks, and the change in hand, with the commands that step through them.
73
+ * NOTE: it tells of no change until every word of both versions is here, since a page still to come would be told as
74
+ * a page taken out. It fetches what is missing once someone listens, and `isPartial` says while it waits.
75
+ * NOTE: how changes are told is left to the comparison made for it: `WordComparison` by runs of words,
76
+ * `ParagraphComparison` by paragraph.
77
+ */
78
+ export class Comparison extends Behaviour {
79
+ constructor(before, after) {
80
+ super([before, after], NOTHING);
81
+ }
82
+ next = () => this.focus(stepFocus(this.get().focused, 1, this.get().changes.length));
83
+ previous = () => this.focus(stepFocus(this.get().focused, -1, this.get().changes.length));
84
+ /** NOTE: takes one change in hand, held inside the range of what changed. Nothing is compared again. */
85
+ focus = (index) => {
86
+ const state = this.get();
87
+ const focused = state.changes.length === 0 ? -1 : Math.min(Math.max(index, 0), state.changes.length - 1);
88
+ if (focused !== state.focused)
89
+ this.change(this.#inHand(state, focused));
90
+ };
91
+ watched() {
92
+ const [before, after] = this.documents;
93
+ if (!before || !after)
94
+ return;
95
+ for (const version of [before, after])
96
+ version.whole().catch(() => undefined);
97
+ }
98
+ follow(state) {
99
+ const [before, after] = this.documents;
100
+ if (!before || !after)
101
+ return NOTHING;
102
+ if (!this.isComplete)
103
+ return WAITING;
104
+ const changes = this.compare(before.pages, after.pages);
105
+ const compared = { ...NOTHING, changes, marksBefore: this.marks(changes, "before"), marksAfter: this.marks(changes, "after") };
106
+ return this.#inHand(compared, changes.length === 0 ? -1 : Math.min(Math.max(state.focused, 0), changes.length - 1));
107
+ }
108
+ #inHand(state, focused) {
109
+ return { ...state, focused, focusedBefore: markIds(state.marksBefore, focused), focusedAfter: markIds(state.marksAfter, focused) };
110
+ }
111
+ }
112
+ /** NOTE: tells each run of words that differs as its own change. */
113
+ export class WordComparison extends Comparison {
114
+ compare(before, after) {
115
+ return compareReadings(before, after);
116
+ }
117
+ marks(changes, side) {
118
+ return comparisonMarks(changes, side);
119
+ }
120
+ }
121
+ /** NOTE: tells changes by paragraph, which reads best as a list. */
122
+ export class ParagraphComparison extends Comparison {
123
+ compare(before, after) {
124
+ return compareParagraphs(before, after);
125
+ }
126
+ marks(changes, side) {
127
+ return paragraphMarks(changes, side);
128
+ }
129
+ }
@@ -0,0 +1,9 @@
1
+ import type { PagemarkDocument } from "../document/index.js";
2
+ import type { ViewerOptions } from "../viewer/index.js";
3
+ /**
4
+ * NOTE: what a viewer needs of an open document to be built: its pages' sizes and its pictures. Hand it to
5
+ * `createViewer` once the document has opened, since the sizes are not known before.
6
+ * NOTE: a document is also told when the screen is idle, with `viewer.on("idle", document.whenIdle)`, and which pages
7
+ * are near the pane, with `viewer.on("pagesNear", document.near)`, so their words are fetched.
8
+ */
9
+ export declare function documentViewerOptions(document: PagemarkDocument): ViewerOptions;
@@ -0,0 +1,9 @@
1
+ /**
2
+ * NOTE: what a viewer needs of an open document to be built: its pages' sizes and its pictures. Hand it to
3
+ * `createViewer` once the document has opened, since the sizes are not known before.
4
+ * NOTE: a document is also told when the screen is idle, with `viewer.on("idle", document.whenIdle)`, and which pages
5
+ * are near the pane, with `viewer.on("pagesNear", document.near)`, so their words are fetched.
6
+ */
7
+ export function documentViewerOptions(document) {
8
+ return { pages: document.sizes, imageUrl: document.pageImage, tileUrl: document.tile, releaseImage: document.release };
9
+ }
@@ -0,0 +1,24 @@
1
+ import { type HiddenRun } from "../core/index.js";
2
+ import type { PagemarkDocument } from "../document/index.js";
3
+ import { Behaviour } from "./behaviour.js";
4
+ import type { HiddenMark } from "./marks.js";
5
+ /** NOTE: one mark for each stretch of hidden words, carrying the stretch, so a reader is shown where a file says something they cannot see. */
6
+ export declare function hiddenMarks(runs: ReadonlyArray<HiddenRun>): HiddenMark[];
7
+ /** NOTE: why a stretch of words is hidden, in words a reader can be shown. */
8
+ export declare function hiddenReason(run: Pick<HiddenRun, "hidden">): string;
9
+ export type HiddenWordsState = {
10
+ runs: HiddenRun[];
11
+ marks: HiddenMark[];
12
+ /** NOTE: how many words the runs hold between them. */
13
+ count: number;
14
+ };
15
+ /**
16
+ * NOTE: the words a document carries that a reader cannot see, gathered from every page as its words arrive. Hidden
17
+ * words may be on any page, so once someone listens it asks for the whole document, as soon as the screen is idle:
18
+ * a list shown beside a document should not hold up its first pictures.
19
+ */
20
+ export declare class HiddenWords extends Behaviour<HiddenWordsState> {
21
+ constructor(document: PagemarkDocument | null);
22
+ protected watched(): void;
23
+ protected follow(): HiddenWordsState;
24
+ }
@@ -0,0 +1,38 @@
1
+ import { hiddenRuns } from "../core/index.js";
2
+ import { Behaviour } from "./behaviour.js";
3
+ /** NOTE: one mark for each stretch of hidden words, carrying the stretch, so a reader is shown where a file says something they cannot see. */
4
+ export function hiddenMarks(runs) {
5
+ return runs.map((run, order) => ({
6
+ id: `hidden-${order}`,
7
+ page: run.page,
8
+ rects: run.rects,
9
+ tone: "hidden",
10
+ label: `Hidden words "${run.text}": ${hiddenReason(run)}`,
11
+ of: { kind: "hidden", order, run },
12
+ }));
13
+ }
14
+ /** NOTE: why a stretch of words is hidden, in words a reader can be shown. */
15
+ export function hiddenReason(run) {
16
+ return run.hidden === "tiny" ? "too small to read" : "nothing shows where it sits";
17
+ }
18
+ const NONE_HIDDEN = { runs: [], marks: [], count: 0 };
19
+ /**
20
+ * NOTE: the words a document carries that a reader cannot see, gathered from every page as its words arrive. Hidden
21
+ * words may be on any page, so once someone listens it asks for the whole document, as soon as the screen is idle:
22
+ * a list shown beside a document should not hold up its first pictures.
23
+ */
24
+ export class HiddenWords extends Behaviour {
25
+ constructor(document) {
26
+ super(document, NONE_HIDDEN);
27
+ }
28
+ watched() {
29
+ const document = this.document;
30
+ document?.idle.then(() => document.whole()).catch(() => undefined);
31
+ }
32
+ follow() {
33
+ const runs = hiddenRuns(this.pages);
34
+ if (runs.length === 0)
35
+ return NONE_HIDDEN;
36
+ return { runs, marks: hiddenMarks(runs), count: runs.reduce((sum, run) => sum + run.lastWord - run.firstWord + 1, 0) };
37
+ }
38
+ }
@@ -0,0 +1,34 @@
1
+ import { type PageReading } from "../core/index.js";
2
+ import type { PagemarkDocument } from "../document/index.js";
3
+ import type { PagePoint, ViewerMark } from "../viewer/index.js";
4
+ import { Behaviour } from "./behaviour.js";
5
+ export type HoveredLine = {
6
+ page: number;
7
+ line: number;
8
+ };
9
+ /** NOTE: the line under the pointer; the one given back is `current` itself when nothing changed, so a caller can skip the update. */
10
+ export declare function hoveredLine(pages: ReadonlyArray<PageReading>, point: PagePoint | null, current: HoveredLine | null): HoveredLine | null;
11
+ export declare function hoverMarks(pages: ReadonlyArray<PageReading>, hovered: HoveredLine | null): ViewerMark[];
12
+ export type LineDescription = {
13
+ page: number;
14
+ text: string;
15
+ source: PageReading["source"];
16
+ sourceReason?: string;
17
+ /** NOTE: the lowest confidence OCR gave any word of the line, or null for a line taken from the text layer. */
18
+ leastSure: number | null;
19
+ /** NOTE: how many of the line's words a reader cannot see. */
20
+ hiddenWords: number;
21
+ };
22
+ export declare function describeLine(pages: ReadonlyArray<PageReading>, hovered: HoveredLine | null): LineDescription | null;
23
+ export type LineHoverState = {
24
+ hovered: HoveredLine | null;
25
+ line: LineDescription | null;
26
+ marks: ViewerMark[];
27
+ };
28
+ /** NOTE: follows the pointer over a document's lines: the line under it, marked, and what was read there. Hand `onPointer` to the viewer. */
29
+ export declare class LineHover extends Behaviour<LineHoverState> {
30
+ #private;
31
+ constructor(document: PagemarkDocument | null);
32
+ readonly onPointer: (point: PagePoint | null) => void;
33
+ protected follow(state: LineHoverState): LineHoverState;
34
+ }
@@ -0,0 +1,49 @@
1
+ import { lineAt, lineText } from "../core/index.js";
2
+ import { Behaviour } from "./behaviour.js";
3
+ /** NOTE: the line under the pointer; the one given back is `current` itself when nothing changed, so a caller can skip the update. */
4
+ export function hoveredLine(pages, point, current) {
5
+ const page = point ? pages[point.page] : undefined;
6
+ const line = point && page ? lineAt(page, point.x, point.y) : null;
7
+ if (!point || line === null)
8
+ return null;
9
+ return current && current.page === point.page && current.line === line ? current : { page: point.page, line };
10
+ }
11
+ export function hoverMarks(pages, hovered) {
12
+ const line = hovered ? pages[hovered.page]?.lines[hovered.line] : undefined;
13
+ return hovered && line ? [{ id: "hover", page: hovered.page, rects: [line.box], tone: "hover" }] : [];
14
+ }
15
+ export function describeLine(pages, hovered) {
16
+ const page = hovered ? pages[hovered.page] : undefined;
17
+ const line = hovered && page ? page.lines[hovered.line] : undefined;
18
+ if (!hovered || !page || !line)
19
+ return null;
20
+ let leastSure = null;
21
+ let hiddenWords = 0;
22
+ for (const word of page.words.slice(line.firstWord, line.lastWord + 1)) {
23
+ if (word.confidence !== undefined)
24
+ leastSure = Math.min(leastSure ?? 100, word.confidence);
25
+ if (word.hidden)
26
+ hiddenWords += 1;
27
+ }
28
+ return { page: hovered.page, text: lineText(page, hovered.line), source: page.source, sourceReason: page.sourceReason, leastSure, hiddenWords };
29
+ }
30
+ const NO_HOVER = { hovered: null, line: null, marks: [] };
31
+ /** NOTE: follows the pointer over a document's lines: the line under it, marked, and what was read there. Hand `onPointer` to the viewer. */
32
+ export class LineHover extends Behaviour {
33
+ constructor(document) {
34
+ super(document, NO_HOVER);
35
+ }
36
+ onPointer = (point) => {
37
+ const state = this.get();
38
+ const hovered = hoveredLine(this.pages, point, state.hovered);
39
+ if (hovered !== state.hovered)
40
+ this.change(this.#over(hovered));
41
+ };
42
+ follow(state) {
43
+ return this.#over(state.hovered);
44
+ }
45
+ #over(hovered) {
46
+ const line = describeLine(this.pages, hovered);
47
+ return hovered && line ? { hovered, line, marks: hoverMarks(this.pages, hovered) } : NO_HOVER;
48
+ }
49
+ }
@@ -0,0 +1,24 @@
1
+ export { Behaviour } from "./behaviour.js";
2
+ export { changeNote, changeSummary, Comparison, comparisonMarks, ParagraphComparison, paragraphMarks, paragraphNote, WordComparison } from "./comparison.js";
3
+ export type { ComparisonState, Side } from "./comparison.js";
4
+ export { documentViewerOptions } from "./document-viewer.js";
5
+ export { hiddenReason, HiddenWords } from "./hidden.js";
6
+ export type { HiddenWordsState } from "./hidden.js";
7
+ export { LineHover } from "./hover.js";
8
+ export type { HoveredLine, LineDescription, LineHoverState } from "./hover.js";
9
+ export { markIds, markOfKind, matchMarks, quoteMarks } from "./marks.js";
10
+ export type { ChangeMark, HiddenMark, Marked, MarkOf, MatchMark, ParagraphMark, QuoteMark } from "./marks.js";
11
+ export { locateQuotes } from "./quotes.js";
12
+ export type { LocatedQuote } from "./quotes.js";
13
+ export { linkViewers } from "./linked-viewers.js";
14
+ export { viewerLinks } from "./links.js";
15
+ export type { LinkableViewer } from "./linked-viewers.js";
16
+ export { BoxSelection } from "./region.js";
17
+ export type { BoxSelectionState, Region } from "./region.js";
18
+ export { Search } from "./search.js";
19
+ export type { QuoteSearch, SearchState } from "./search.js";
20
+ export { WordSelection } from "./selection.js";
21
+ export type { WordRange, WordSelectionState } from "./selection.js";
22
+ export { textLines } from "./text.js";
23
+ export { NO_VIEWER, viewerState } from "./viewer-state.js";
24
+ export type { ViewerState, WatchableViewer } from "./viewer-state.js";
@@ -0,0 +1,14 @@
1
+ export { Behaviour } from "./behaviour.js";
2
+ export { changeNote, changeSummary, Comparison, comparisonMarks, ParagraphComparison, paragraphMarks, paragraphNote, WordComparison } from "./comparison.js";
3
+ export { documentViewerOptions } from "./document-viewer.js";
4
+ export { hiddenReason, HiddenWords } from "./hidden.js";
5
+ export { LineHover } from "./hover.js";
6
+ export { markIds, markOfKind, matchMarks, quoteMarks } from "./marks.js";
7
+ export { locateQuotes } from "./quotes.js";
8
+ export { linkViewers } from "./linked-viewers.js";
9
+ export { viewerLinks } from "./links.js";
10
+ export { BoxSelection } from "./region.js";
11
+ export { Search } from "./search.js";
12
+ export { WordSelection } from "./selection.js";
13
+ export { textLines } from "./text.js";
14
+ export { NO_VIEWER, viewerState } from "./viewer-state.js";
@@ -0,0 +1,14 @@
1
+ import type { Viewer, ViewMove } from "../viewer/index.js";
2
+ /** NOTE: the part of a viewer a link needs, so a test, or a caller's own viewer, can stand in for one. */
3
+ export type LinkableViewer = Pick<Viewer, "zoom" | "zoomTo" | "moveBy"> & {
4
+ on(event: "view", listener: (move: ViewMove) => void): () => void;
5
+ };
6
+ /**
7
+ * NOTE: keeps viewers side by side in step: a zoom in one is the same zoom in the others, and a reader's scroll in
8
+ * one moves the others the same distance on the page. Each keeps its own place, so two versions whose words sit at
9
+ * different heights stay on the same change while they are read, and a viewer that brings its own mark into view
10
+ * takes nobody with it. It returns the function that unlinks them.
11
+ */
12
+ export declare function linkViewers(viewers: ReadonlyArray<LinkableViewer>, options?: {
13
+ scroll?: boolean;
14
+ }): () => void;
@@ -0,0 +1,25 @@
1
+ /** NOTE: two zooms this close, as a share of the zoom, are the same zoom; a viewer following another must not be told to follow back. */
2
+ const SAME_ZOOM = 0.0005;
3
+ /**
4
+ * NOTE: keeps viewers side by side in step: a zoom in one is the same zoom in the others, and a reader's scroll in
5
+ * one moves the others the same distance on the page. Each keeps its own place, so two versions whose words sit at
6
+ * different heights stay on the same change while they are read, and a viewer that brings its own mark into view
7
+ * takes nobody with it. It returns the function that unlinks them.
8
+ */
9
+ export function linkViewers(viewers, options = {}) {
10
+ const movesTogether = options.scroll ?? true;
11
+ const stops = viewers.map((leader) => leader.on("view", (move) => {
12
+ for (const follower of viewers) {
13
+ if (follower === leader)
14
+ continue;
15
+ if (Math.abs(follower.zoom - move.zoom) > move.zoom * SAME_ZOOM)
16
+ follower.zoomTo(move.zoom);
17
+ if (movesTogether && move.byReader && (move.x !== 0 || move.y !== 0))
18
+ follower.moveBy(move.x, move.y);
19
+ }
20
+ }));
21
+ return () => {
22
+ for (const stop of stops)
23
+ stop();
24
+ };
25
+ }
@@ -0,0 +1,4 @@
1
+ import type { PageReading } from "../core/index.js";
2
+ import type { ViewerLink } from "../viewer/index.js";
3
+ /** NOTE: every link the pages' readings carry, as the viewer takes them. */
4
+ export declare function viewerLinks(pages: ReadonlyArray<PageReading>): ViewerLink[];
@@ -0,0 +1,4 @@
1
+ /** NOTE: every link the pages' readings carry, as the viewer takes them. */
2
+ export function viewerLinks(pages) {
3
+ return pages.flatMap((page) => (page.links ?? []).map((link) => ("url" in link ? { page: page.index, box: link.box, url: link.url } : { page: page.index, box: link.box, toPage: link.page })));
4
+ }