@readium/navigator 2.11.1 → 2.12.0

package/src/webpub/WebPubNavigator.ts

@@ -2,7 +2,7 @@ import { Feature, Link, Locator, LocatorText, Publication, ReadingProgression, L
 import { VisualNavigator, VisualNavigatorViewport, ProgressionRange, KeyboardPeripheralEventData } from "../Navigator.ts";
 import { Configurable } from "../preferences/Configurable.ts";
 import { WebPubFramePoolManager } from "./WebPubFramePoolManager.ts";
-import { BasicTextSelection, CommsEventKey, ContextMenuEvent, DecorationActivatedEvent, DecorationPointerEnterData, DecorationPointerLeaveData, FrameClickEvent, KeyboardPeripheralEvent, ModuleName, SuspiciousActivityEvent, WebPubModules } from "@readium/navigator-html-injectables";
+import { BasicTextSelection, CommsEventKey, ContextMenuEvent, DecorationActivatedEvent, DecorationPointerEnterData, DecorationPointerLeaveData, FrameClickEvent, KeyboardPeripheralEvent, ModuleName, SuspiciousActivityEvent, TextLayout, PointedPieceRequest, PointedPieceResponse, WebPubModules } from "@readium/navigator-html-injectables";
 import * as path from "path-browserify";
 import { WebPubFrameManager } from "./WebPubFrameManager.ts";
 import { Decoration, DecorableNavigator, OnDecorationActivatedEvent, OnDecorationPointerEnterEvent, OnDecorationPointerLeaveEvent, DecorationObserver, DecoratorConfig, decorationsEqual, resolveDecorationForWire, supportsDecorationStyle as canRenderDecorationStyle, DecorationStyleType } from "../decorations/index.ts";
@@ -46,6 +46,9 @@ export interface WebPubNavigatorListeners {
     peripheral: (data: KeyboardPeripheralEventData) => void;
 }
 
+// Expired comms callbacks are dropped, never called.
+const POINTED_PIECE_TIMEOUT = 1000;
+
 const defaultListeners = (listeners: WebPubNavigatorListeners): WebPubNavigatorListeners => ({
     frameLoaded: listeners.frameLoaded || (() => {}),
     positionChanged: listeners.positionChanged || (() => {}),
@@ -102,6 +105,11 @@ export class WebPubNavigator extends VisualNavigator implements Configurable<Web
     private _decorationHoverState: Map<string, boolean> = new Map();
     private _decorationActivationConsumed = false;
     private _decorationResizeSelectors: Set<string>;
+    private _textLayoutWatch?: { href: string; pieces: unknown[]; cb: (layout: TextLayout) => void };
+    private _textLayoutFrame?: WebPubFrameManager;
+    private _navigationLocked = false;
+    private readonly _pointedPieceRequests = new Map<string, (index: number) => void>();
+    private _pointedPieceRequestId = 0;
 
     private webViewport: VisualNavigatorViewport = {
         readingOrder: [],
@@ -283,14 +291,25 @@ export class WebPubNavigator extends VisualNavigator implements Configurable<Web
         ) ?? false;
     }
 
-    public eventListener(key: CommsEventKey | ManagerEventKey, data: unknown) {
+    public eventListener(key: CommsEventKey | ManagerEventKey, data: unknown, sourceFrame?: WebPubFrameManager) {
         switch (key) {
             case "_pong":
                 this.listeners.frameLoaded(this.framePool.currentFrames[0]!.iframe.contentWindow!);
                 this.listeners.positionChanged(this.currentLocation);
                 this._notifyTimelineChange(this.currentLocation);
                 this._reapplyDecorationsToCurrentFrame();
+                this._watchTextLayoutInCurrentFrame(true);
+                this._sendNavigationLock();
+                break;
+            case "text_layout":
+                // A frame being hidden after moving to another resource lays out again, collapsed.
+                if (sourceFrame && sourceFrame === this._textLayoutFrame && this.currentLocation.href.split("#")[0] === this._textLayoutWatch?.href) this._textLayoutWatch.cb(data as TextLayout);
                 break;
+            case "pointed_piece": {
+                const { id, index } = data as PointedPieceResponse;
+                this._pointedPieceRequests.get(id)?.(index);
+                break;
+            }
             case "first_visible_locator":
                 const loc = Locator.deserialize(data as string);
                 if(!loc) break;
@@ -340,7 +359,7 @@ export class WebPubNavigator extends VisualNavigator implements Configurable<Web
                     ) {
                         const origHref = element.attributes.getNamedItem("href")?.value!;
                         if (origHref.startsWith("#")) {
-                            this.go(this.currentLocation.copyWithLocations({
+                            if (!this._navigationLocked) this.go(this.currentLocation.copyWithLocations({
                                 fragments: [origHref.substring(1)]
                             }), false, () => { });
                         } else if(
@@ -374,7 +393,7 @@ export class WebPubNavigator extends VisualNavigator implements Configurable<Web
 
                                 const link = this.pub.readingOrder.findWithHref(hrefToCheck);
                                 if (link) {
-                                    this.goLink(link, false, () => { });
+                                    if (!this._navigationLocked) this.goLink(link, false, () => { });
                                 } else {
                                     console.warn(`Internal link not found in readingOrder: ${hrefToCheck}`);
                                     this.listeners.handleLocator(new Link({
@@ -400,9 +419,13 @@ export class WebPubNavigator extends VisualNavigator implements Configurable<Web
             case "zoom":
                 this.listeners.zoom(data as number);
                 break;
-            case "progress":
+            case "progress": {
+                // The previous resource's frame can still report once moving to another, which would take its progress.
+                const frame = sourceFrame && this.framePool._frameFor(this.currentLocation.href.split("#")[0]);
+                if (sourceFrame && sourceFrame !== frame) break;
                 this.syncLocation(data as ProgressionRange);
                 break;
+            }
             case "content_protection":
                 const activity = data as SuspiciousActivityEvent;
                 this.listeners.contentProtection(activity.type, activity);
@@ -442,12 +465,15 @@ export class WebPubNavigator extends VisualNavigator implements Configurable<Web
     }
 
     private attachListener() {
-        if (this.framePool.currentFrames[0]?.msg) {
-            this.framePool.currentFrames[0].msg.listener = (key: CommsEventKey | ManagerEventKey, value: unknown) => {
-                this.eventListener(key, value);
-            };
-        }
+        const vframes = this.framePool.currentFrames.filter(f => !!f) as WebPubFrameManager[];
+        vframes.forEach(f => {
+            if(f.msg) f.msg.listener = (key: CommsEventKey | ManagerEventKey, value: unknown) => {
+                this.eventListener(key, value, f);
+            }
+        })
         this._reapplyDecorationsToCurrentFrame();
+        this._watchTextLayoutInCurrentFrame();
+        this._sendNavigationLock();
     }
 
     private async apply() {
@@ -619,6 +645,84 @@ export class WebPubNavigator extends VisualNavigator implements Configurable<Web
         }
     }
 
+    /**
+     * Reports where the text of `locators`, all in one resource, starts each line along the scroll axis,
+     * with the viewport. Reported again whenever that resource is scrolled or laid out again.
+     * Replaces any previous watch, and returns a function that stops this one.
+     */
+    public watchTextLayout(locators: Locator[], cb: (layout: TextLayout) => void): () => void {
+        const watch = {
+            href: locators[0]?.href.split("#")[0] ?? "",
+            pieces: locators.map(locator => [locator.text?.serialize(), getCssSelector(locator.locations)]),
+            cb,
+        };
+        this._textLayoutWatch = watch;
+        this._watchTextLayoutInCurrentFrame(true);
+        return () => {
+            if (this._textLayoutWatch !== watch) return;
+            this._textLayoutWatch = undefined;
+            this._watchTextLayoutInCurrentFrame();
+        };
+    }
+
+    /**
+     * Locks or unlocks navigating in the content: scrolling and following its links.
+     * Calls to the navigator still move it.
+     */
+    public lockNavigation(locked: boolean): void {
+        this._navigationLocked = locked;
+        this._sendNavigationLock();
+    }
+
+    private _sendNavigationLock(): void {
+        this.framePool?.currentFrames[0]?.msg?.send("lock_navigation", this._navigationLocked);
+    }
+
+    /**
+     * Returns the first of `pieces` under the point of `event`, else the first containing the element it targets,
+     * in the resource of the frame it comes from. Undefined when none does.
+     */
+    public async findPointedPiece(event: FrameClickEvent, pieces: Locator[]): Promise<Locator | undefined> {
+        const frames = this.framePool.currentFrames.filter(f => !!f) as WebPubFrameManager[];
+        const i = frames.findIndex(frame => frame.source === event.targetFrameSrc);
+        const href = i >= 0 ? this.viewport.readingOrder[i] : undefined;
+        if (!href || !event.cssSelector) return undefined;
+        const candidates = pieces.filter(piece => piece.href.split("#")[0] === href);
+        if (candidates.length === 0) return undefined;
+
+        const id = `${++this._pointedPieceRequestId}`;
+        let timeout: ReturnType<typeof setTimeout> | undefined;
+        const index = await new Promise<number>(resolve => {
+            this._pointedPieceRequests.set(id, resolve);
+            timeout = setTimeout(() => resolve(-1), POINTED_PIECE_TIMEOUT);
+            const request: PointedPieceRequest = {
+                id,
+                cssSelector: event.cssSelector!,
+                x: event.x,
+                y: event.y,
+                pieces: candidates.map(piece => [piece.text?.serialize(), getCssSelector(piece.locations)])
+            };
+            // The reply is posted before the ack, so a pending request on ack got no reply.
+            const sent = frames[i].msg?.send("pointed_piece", request, () => resolve(-1));
+            if (!sent) resolve(-1);
+        });
+        clearTimeout(timeout);
+        this._pointedPieceRequests.delete(id);
+        return candidates[index];
+    }
+
+    // The previous frame stops watching, so only the displayed resource reports its layout.
+    private _watchTextLayoutInCurrentFrame(resend = false): void {
+        const frame = this.framePool?.currentFrames[0];
+        const watch = this._textLayoutWatch;
+        const target = watch && frame && this.currentLocation?.href.split("#")[0] === watch.href ? frame : undefined;
+        if (target === this._textLayoutFrame && !resend) return;
+        const previous = this._textLayoutFrame;
+        if (previous && previous !== target && !previous.isDestroyed) previous.msg?.send("watch_text_layout", []);
+        this._textLayoutFrame = target;
+        if (target && watch) target.msg?.send("watch_text_layout", watch.pieces);
+    }
+
     private _handleDecorationActivated(data: DecorationActivatedEvent): boolean {
         const observers = this._decorationObservers.get(data.group);
         if (!observers || observers.size === 0) return false;

package/types/src/epub/EpubNavigator.d.ts

@@ -2,7 +2,7 @@ import { Layout, Link, Locator, Publication, ReadingProgression, Timeline, Timel
 import { Configurable, ConfigurableSettings, VisualNavigator, VisualNavigatorViewport } from "../index.ts";
 import { FramePoolManager } from "./frame/FramePoolManager.ts";
 import { FXLFramePoolManager } from "./fxl/FXLFramePoolManager.ts";
-import { CommsEventKey, ContextMenuEvent, BasicTextSelection, FrameClickEvent, SuspiciousActivityEvent } from "@readium/navigator-html-injectables";
+import { CommsEventKey, ContextMenuEvent, BasicTextSelection, FrameClickEvent, SuspiciousActivityEvent, TextLayout } from "@readium/navigator-html-injectables";
 import { Decoration, DecorationObserver, DecorableNavigator, DecoratorConfig, DecorationStyleType } from "../decorations/index.ts";
 import { FXLFrameManager } from "./fxl/FXLFrameManager.ts";
 import { FrameManager } from "./frame/FrameManager.ts";
@@ -81,6 +81,11 @@ export declare class EpubNavigator extends VisualNavigator implements Configurab
     private _decorationHoverState;
     private _decorationActivationConsumed;
     private _decorationResizeSelectors;
+    private _textLayoutWatch?;
+    private _textLayoutFrame?;
+    private _navigationLocked;
+    private readonly _pointedPieceRequests;
+    private _pointedPieceRequestId;
     private reflowViewport;
     constructor(container: HTMLElement, pub: Publication, listeners: EpubNavigatorListeners, positions?: Locator[], initialPosition?: Locator | undefined, configuration?: EpubNavigatorConfiguration);
     static determineLayout(pub: Publication, scroll?: boolean): Layout;
@@ -126,6 +131,26 @@ export declare class EpubNavigator extends VisualNavigator implements Configurab
     private _sendDecorationOps;
     private _reapplyDecorationsToFrame;
     private _reapplyDecorationsToCurrentFrames;
+    /**
+     * Reports where the text of `locators`, all in one reflowable resource, starts each line or column
+     * along the scroll axis, with the viewport. Reported again whenever that resource is scrolled or laid out again.
+     * Replaces any previous watch, and returns a function that stops this one.
+     */
+    watchTextLayout(locators: Locator[], cb: (layout: TextLayout) => void): () => void;
+    /**
+     * Locks or unlocks navigating in the content: scrolling, swiping, tapping its edges and following its links.
+     * Calls to the navigator still move it.
+     */
+    lockNavigation(locked: boolean): void;
+    private _sendNavigationLock;
+    /** The left page's width when `targetFrameSrc` is the right page (screen-wise) of a fixed-layout spread, else 0. */
+    private _spreadOffsetX;
+    /**
+     * Returns the first of `pieces` under the point of `event`, else the first containing the element it targets,
+     * in the resource of the frame it comes from. Undefined when none does.
+     */
+    findPointedPiece(event: FrameClickEvent, pieces: Locator[]): Promise<Locator | undefined>;
+    private _watchTextLayoutInCurrentFrame;
     private _handleDecorationActivated;
     private _handleDecorationPointerEnter;
     private _handleDecorationPointerLeave;

package/types/src/epub/frame/FramePoolManager.d.ts

@@ -33,5 +33,7 @@ export declare class FramePoolManager {
         [key: string]: string;
     }): void;
     get currentFrames(): (FrameManager | undefined)[];
+    /** The pooled frame of `href`, whether or not it's shown. */
+    _frameFor(href: string): FrameManager | undefined;
     get currentBounds(): DOMRect;
 }

package/types/src/index.d.ts

@@ -8,3 +8,4 @@ export * from './helpers/index.ts';
 export * from './preferences/index.ts';
 export * from './css/index.ts';
 export * from './injection/index.ts';
+export * from './readaloud/index.ts';

package/types/src/preferences/guards.d.ts

@@ -7,5 +7,6 @@ export declare function ensureEnumValue<T extends string>(value: T | null | unde
 export declare function ensureFilter(filter: boolean | number | null | undefined): boolean | number | null | undefined;
 export declare function ensureNonNegative(value: number | null | undefined): number | null | undefined;
 export declare function ensureValueInRange(value: number | null | undefined, range: [number, number]): number | null | undefined;
+export declare function ensureDecorationStyle<T extends object>(value: T | false | null | undefined): T | false | null | undefined;
 export declare function withFallback<T>(value: T | null | undefined, defaultValue: T | null): T | null;
 export declare function ensureExperiment(experimentsInput: ExperimentKey[] | null | undefined): ExperimentKey[] | null | undefined;

package/types/src/readaloud/GuidedNavigationProvider.d.ts

@@ -0,0 +1,28 @@
+import { GuidedNavigationObject, Link, Publication } from "@readium/shared";
+export interface GuidedNavigationProvider {
+    /**
+     * Guided Navigation objects of a resource, with every textref qualified by the resource's href.
+     * Resolves to undefined when the resource has nothing to read.
+     */
+    guideFor(link: Link): Promise<GuidedNavigationObject[] | undefined>;
+}
+export interface PublicationGuidedNavigationProviderOptions {
+    /** Generates from the resource's markup without using the publication's Guided Navigation document. */
+    generateFromMarkup?: boolean;
+}
+/**
+ * Uses the publication's Guided Navigation document when its text can be located in the resource,
+ * and generates one from the resource's markup otherwise, or always with `generateFromMarkup`.
+ * Only the objects of the resource are kept from a document covering the whole publication.
+ */
+export declare class PublicationGuidedNavigationProvider implements GuidedNavigationProvider {
+    private readonly publication;
+    private readonly options;
+    constructor(publication: Publication, options?: PublicationGuidedNavigationProviderOptions);
+    guideFor(link: Link): Promise<GuidedNavigationObject[] | undefined>;
+    private generate;
+    private objectsIn;
+    private resourceOf;
+    private imageOf;
+    private isLocatable;
+}

package/types/src/readaloud/ReadAloudNavigator.d.ts

@@ -0,0 +1,158 @@
+import { Layout, Locator } from "@readium/shared";
+import { FrameClickEvent, TextLayout } from "@readium/navigator-html-injectables";
+import { ReadiumSpeechPlaybackEngine, ReadiumSpeechPlaybackState, ReadiumSpeechVoice } from "@readium/speech";
+import { Navigator, VisualNavigatorViewport } from "../Navigator.ts";
+import { DecorableNavigator } from "../decorations/index.ts";
+import { GuidedNavigationProvider } from "./GuidedNavigationProvider.ts";
+import { IReadAloudDefaults, IReadAloudPreferences, ReadAloudPreferences, ReadAloudPreferencesEditor, ReadAloudSettings } from "./preferences/index.ts";
+export type ReadAloudState = ReadiumSpeechPlaybackState;
+export interface ReadAloudVoicesOptions {
+    /** BCP 47 tags, matched by base language. */
+    languages?: string[];
+}
+export interface ReadAloudUtterance {
+    text: string;
+    /** One locator per piece of the utterance, each in its own resource. */
+    locators: Locator[];
+}
+export interface ReadAloudListeners {
+    stateChanged?: (state: ReadAloudState) => void;
+    utteranceChanged?: (utterance: ReadAloudUtterance) => void;
+    wordChanged?: (locator: Locator, word: string) => void;
+    error?: (error: unknown) => void;
+}
+export interface ReadAloudConfiguration {
+    /** Defaults to a `WebSpeechEngine`. */
+    engine?: ReadiumSpeechPlaybackEngine;
+    provider?: GuidedNavigationProvider;
+    preferences?: IReadAloudPreferences;
+    defaults?: IReadAloudDefaults;
+    /**
+     * Whether the reader can move away while reading aloud, which then stops following until back.
+     * Otherwise navigating in the content is locked while playing. Defaults to true.
+     */
+    detachable?: boolean;
+}
+/**
+ * Reads a publication aloud with a speech engine, alongside the navigator displaying it.
+ * The spoken utterance and word are highlighted, and the navigator follows them.
+ */
+export declare class ReadAloudNavigator {
+    private readonly navigator;
+    private readonly listeners;
+    private readonly speech;
+    private readonly pool;
+    private readonly units;
+    private readonly unsubscribers;
+    private readonly _defaults;
+    private _preferences;
+    private _settings;
+    private _preferencesEditor;
+    private utteranceLocators;
+    private wordLocator?;
+    private pausedBefore?;
+    private turning?;
+    private followedHref?;
+    private following?;
+    private detached;
+    private navigationLocked;
+    private shownHref?;
+    private watchedPieces;
+    private unwatchLayout?;
+    private lines;
+    private viewport?;
+    private readonly progress;
+    private breakTimer?;
+    private unit?;
+    private loading;
+    private loadPaused;
+    private loadToken;
+    private settleReady?;
+    private lastState;
+    constructor(navigator: Navigator & Partial<DecorableNavigator> & {
+        readonly viewport?: VisualNavigatorViewport;
+        readonly layout?: Layout;
+        watchTextLayout?(locators: Locator[], cb: (layout: TextLayout) => void): () => void;
+        findPointedPiece?(event: FrameClickEvent, pieces: Locator[]): Promise<Locator | undefined>;
+        lockNavigation?(locked: boolean): void;
+    }, listeners?: ReadAloudListeners, configuration?: ReadAloudConfiguration);
+    /** Whether the reader can move away while reading aloud. Otherwise the app keeps its own navigation from moving while playing. */
+    readonly detachable: boolean;
+    get state(): ReadAloudState;
+    /**
+     * Starts reading from `from`, or resumes when paused.
+     * Without `from`, an idle reader starts from the navigator's current position.
+     */
+    play(from?: Locator): Promise<void>;
+    /**
+     * Starts reading from the utterance under a click or tap in a displayed resource, loading that resource when needed.
+     * Resolves false when the press isn't on content read aloud, or is on an interactive element, so the caller handles it.
+     */
+    readFromPointer(event: FrameClickEvent): Promise<boolean>;
+    pause(): void;
+    stop(): void;
+    /** Moves to the next utterance, continuing into the next reading unit at the end of this one. */
+    next(): Promise<boolean>;
+    /** Moves to the previous utterance, continuing into the previous reading unit at the start of this one. */
+    previous(): Promise<boolean>;
+    /**
+     * The available voices, only those of `languages` when given,
+     * ranked the way the default voice is picked: preferred region first, then quality.
+     */
+    getVoices(options?: ReadAloudVoicesOptions): Promise<ReadiumSpeechVoice[]>;
+    setVoice(voice: ReadiumSpeechVoice | string): void;
+    getCurrentVoice(): ReadiumSpeechVoice | null;
+    get settings(): Readonly<ReadAloudSettings>;
+    get preferencesEditor(): ReadAloudPreferencesEditor;
+    submitPreferences(preferences: ReadAloudPreferences): Promise<void>;
+    destroy(): Promise<void>;
+    private listen;
+    private start;
+    private resumePaused;
+    private speechReady;
+    private untilReady;
+    private movePaused;
+    private loadUnit;
+    private startIndex;
+    private indexAfterRebuild;
+    private pointedIndex;
+    private piecesOf;
+    private speakFrom;
+    private pausesAtPages;
+    private turnTo;
+    private staysPaused;
+    private pauseTurning;
+    private pausesBeforeUnit;
+    private pausesBetween;
+    private hrefsOf;
+    private notifyUtterance;
+    private pageLocator;
+    private decorate;
+    private applyDecorations;
+    private clearHighlights;
+    private follow;
+    private attach;
+    private isDetached;
+    private watchLayout;
+    private laidOut;
+    private isHidden;
+    private lineStart;
+    private spokenPoint;
+    private utteranceStart;
+    private wordPoint;
+    private pointAt;
+    private pointLocator;
+    private armBreak;
+    private clearBreak;
+    private sendsBoundaries;
+    private voiceName;
+    private speed;
+    private static collapsed;
+    private static rawOffset;
+    private locatorFor;
+    private layout;
+    private static speechPreferences;
+    private setLoading;
+    private lockNavigation;
+    private notifyState;
+}

package/types/src/readaloud/ReadingUnit.d.ts

@@ -0,0 +1,58 @@
+import { GuidedNavigationObject, Link, Publication } from "@readium/shared";
+import { Navigator, VisualNavigatorViewport } from "../Navigator.ts";
+import { GuidedNavigationProvider } from "./GuidedNavigationProvider.ts";
+/** Reading order links whose Guided Navigation objects are read as one sequence. */
+export interface ReadingUnit {
+    links: Link[];
+}
+/**
+ * Splits the publication into reading units: the displayed spread for fixed layouts, Divina excepted,
+ * and a single resource otherwise. Spreads are only known to the navigator, so it's moved to find them;
+ * FXL navigators update their viewport synchronously, so it's read without waiting for the callback.
+ */
+export declare class ReadingUnits {
+    private readonly navigator;
+    private readonly spreads;
+    constructor(navigator: Navigator & {
+        readonly viewport?: VisualNavigatorViewport;
+    });
+    /** The unit containing `href`. */
+    around(href: string): ReadingUnit | undefined;
+    /** The first link of the unit following `unit`, without moving the navigator. */
+    linkAfter(unit: ReadingUnit): Link | undefined;
+    /** The last link of the unit preceding `unit`, without moving the navigator. */
+    linkBefore(unit: ReadingUnit): Link | undefined;
+    after(unit: ReadingUnit): ReadingUnit | undefined;
+    before(unit: ReadingUnit): ReadingUnit | undefined;
+    /** Whether `href` is a page of the displayed spread. */
+    displays(href: string): boolean;
+    private move;
+    private displayedFrom;
+    private indexOf;
+}
+export interface StitchedUnit {
+    /** The unit's Guided Navigation objects, concatenated in reading order. */
+    guided: GuidedNavigationObject[];
+    /** Links whose objects couldn't be obtained, left out of `guided`. */
+    failures: {
+        link: Link;
+        error: unknown;
+    }[];
+}
+/**
+ * Keeps the Guided Navigation objects of the resources around the unit being read,
+ * fetching those within LOWER_BOUNDARY reading order items and releasing those beyond UPPER_BOUNDARY.
+ */
+export declare class GuidedNavigationPool {
+    private readonly publication;
+    private readonly provider;
+    private readonly guides;
+    constructor(publication: Publication, provider: GuidedNavigationProvider);
+    /**
+     * Concatenates the Guided Navigation objects of every link in the unit, in reading order,
+     * fetching at most `concurrency` resources at once, then fetches the unit's neighbours.
+     */
+    stitch(unit: ReadingUnit, concurrency?: number): Promise<StitchedUnit>;
+    private update;
+    private guideFor;
+}

package/types/src/readaloud/SpeechProgress.d.ts

@@ -0,0 +1,19 @@
+import { ReadiumSpeechUtterance } from "@readium/speech";
+/** Times the utterance being spoken, and measures each voice's speed on the utterances it finishes. */
+export declare class SpeechProgress {
+    private readonly speeds;
+    private utterance?;
+    private startedAt;
+    private pausedAt?;
+    start(utterance: ReadiumSpeechUtterance): void;
+    pause(): void;
+    resume(): void;
+    /** Measures the speed of `voice` once it has spoken `utterance` through. */
+    end(utterance: ReadiumSpeechUtterance | null, voice: string, rate: number): void;
+    reset(): void;
+    get speaking(): boolean;
+    /** Seconds spent speaking the current utterance. */
+    elapsed(): number;
+    /** Characters per second of `voice` at `rate`. */
+    speed(voice: string, rate: number): number;
+}

package/types/src/readaloud/index.d.ts

@@ -0,0 +1,6 @@
+export * from './GuidedNavigationProvider.ts';
+export * from './ReadAloudNavigator.ts';
+export * from './preferences/index.ts';
+export { defaultContextualizations, skippableRoles, filterByLanguages, filterOutNoveltyVoices, filterOutVeryLowQualityVoices, getQualityValue, groupVoicesByLanguage, sortAlphabetically, sortByQuality, sortVoicesByRegions } from "@readium/speech";
+export type { ExtractionFormat, LanguageMode, ReadiumSpeechPlaybackEngine, ReadiumSpeechVoice, Segmentation, VerbosityPreset } from "@readium/speech";
+export type { GndRole } from "@readium/guided-navigation";

package/types/src/readaloud/preferences/ReadAloudDefaults.d.ts

@@ -0,0 +1,11 @@
+import { IReadAloudPreferences, ReadAloudAutoPause, ReadAloudDecorationStyle } from "./ReadAloudPreferences.ts";
+export type IReadAloudDefaults = IReadAloudPreferences;
+export declare class ReadAloudDefaults {
+    /** Defaults of the speech fields, validated by speech itself. */
+    speech: IReadAloudPreferences;
+    autoPause: ReadAloudAutoPause;
+    speakInContentLanguage: boolean;
+    utteranceStyle: ReadAloudDecorationStyle;
+    wordStyle: ReadAloudDecorationStyle;
+    constructor(defaults?: IReadAloudDefaults);
+}

package/types/src/readaloud/preferences/ReadAloudPreferences.d.ts

@@ -0,0 +1,58 @@
+import type { GndRole } from "@readium/guided-navigation";
+import { ExtractionFormat, LanguageMode, Segmentation, VerbosityPreset } from "@readium/speech";
+import { ConfigurablePreferences } from "../../preferences/Configurable.ts";
+import { BuiltinDecorationStyle, NamedDecorationStyle } from "../../decorations/index.ts";
+/**
+ * When playback pauses on its own: never, after every utterance, before every block,
+ * or before the first utterance starting on another page or outside the displayed spread.
+ */
+export declare const ReadAloudAutoPause: {
+    readonly none: "none";
+    readonly utterance: "utterance";
+    readonly block: "block";
+    readonly page: "page";
+    readonly spread: "spread";
+};
+export type ReadAloudAutoPause = typeof ReadAloudAutoPause[keyof typeof ReadAloudAutoPause];
+/** A decoration style, or `false` to not decorate at all. */
+export type ReadAloudDecorationStyle = BuiltinDecorationStyle | NamedDecorationStyle | false;
+export interface IReadAloudPreferences {
+    format?: ExtractionFormat | null;
+    inlineContextualization?: boolean | null;
+    verbosity?: VerbosityPreset | null;
+    skip?: GndRole[] | null;
+    contextualize?: GndRole[] | null;
+    language?: LanguageMode | null;
+    segmentation?: Segmentation | null;
+    pauseDuration?: number | null;
+    autoPause?: ReadAloudAutoPause | null;
+    speakInContentLanguage?: boolean | null;
+    rate?: number | null;
+    pitch?: number | null;
+    volume?: number | null;
+    /** Style of the utterance being spoken */
+    utteranceStyle?: ReadAloudDecorationStyle | null;
+    /** Style of the word being spoken */
+    wordStyle?: ReadAloudDecorationStyle | null;
+}
+export declare class ReadAloudPreferences implements ConfigurablePreferences<ReadAloudPreferences> {
+    format?: ExtractionFormat | null;
+    inlineContextualization?: boolean | null;
+    verbosity?: VerbosityPreset | null;
+    skip?: GndRole[] | null;
+    contextualize?: GndRole[] | null;
+    language?: LanguageMode | null;
+    segmentation?: Segmentation | null;
+    pauseDuration?: number | null;
+    autoPause?: ReadAloudAutoPause | null;
+    speakInContentLanguage?: boolean | null;
+    rate?: number | null;
+    pitch?: number | null;
+    volume?: number | null;
+    utteranceStyle?: ReadAloudDecorationStyle | null;
+    wordStyle?: ReadAloudDecorationStyle | null;
+    constructor(preferences?: IReadAloudPreferences);
+    static serialize(preferences: ReadAloudPreferences): string;
+    static deserialize(preferences: string): ReadAloudPreferences | null;
+    merging(other: ReadAloudPreferences): ReadAloudPreferences;
+}

package/types/src/readaloud/preferences/ReadAloudPreferencesEditor.d.ts

@@ -0,0 +1,37 @@
+import { Layout } from "@readium/shared";
+import { SpeechSettings } from "@readium/speech";
+import { IPreferencesEditor } from "../../preferences/PreferencesEditor.ts";
+import { BooleanPreference, EnumPreference, Preference } from "../../preferences/Preference.ts";
+import { ReadAloudAutoPause, ReadAloudDecorationStyle, ReadAloudPreferences } from "./ReadAloudPreferences.ts";
+import { ReadAloudSettings } from "./ReadAloudSettings.ts";
+/**
+ * Edits read-aloud preferences, speech's own fields through speech's editor.
+ */
+export declare class ReadAloudPreferencesEditor implements IPreferencesEditor {
+    private speech;
+    private own;
+    private settings;
+    private layout;
+    /**
+     * @param layout How the publication is displayed: `Layout.reflowable` for columns, `Layout.scrolled` when scrolled.
+     */
+    constructor(initialPreferences: ReadAloudPreferences, settings: ReadAloudSettings, speechSettings: SpeechSettings, layout: Layout);
+    get preferences(): ReadAloudPreferences;
+    clear(): void;
+    private updatePreference;
+    get format(): import("@readium/speech").EnumPreference<import("@readium/speech").ExtractionFormat>;
+    get inlineContextualization(): import("@readium/speech").BooleanPreference;
+    get verbosity(): import("@readium/speech").EnumPreference<import("@readium/speech").VerbosityPreset>;
+    get skip(): import("@readium/speech").StringArrayPreference;
+    get contextualize(): import("@readium/speech").StringArrayPreference;
+    get language(): import("@readium/speech").EnumPreference<import("@readium/speech").LanguageMode>;
+    get segmentation(): import("@readium/speech").EnumPreference<import("@readium/speech").Segmentation>;
+    get pauseDuration(): import("@readium/speech").RangePreference<number>;
+    get rate(): import("@readium/speech").RangePreference<number>;
+    get pitch(): import("@readium/speech").RangePreference<number>;
+    get volume(): import("@readium/speech").RangePreference<number>;
+    get autoPause(): EnumPreference<ReadAloudAutoPause>;
+    get speakInContentLanguage(): BooleanPreference;
+    get utteranceStyle(): Preference<ReadAloudDecorationStyle>;
+    get wordStyle(): Preference<ReadAloudDecorationStyle>;
+}