@nulib/clover 4.0.0-beta.1 → 4.1.0

package/dist/index.d.mts

@@ -52,8 +52,10 @@ export interface LocalizedValue {
 export declare function localize(value: LanguageMapLike, language?: string, separator?: string): LocalizedValue;
 /**
  * What an annotation says: its text bodies (plain, HTML or Markdown, as their `format`
- * says) and its images (Cookbook 0377). Caption files belong to the media transcript, so
- * are left out. Light, for the Canvas's caption as well as the lists.
+ * says), its images (Cookbook 0377) and its named places (Cookbook 0139), each read too
+ * where a `SpecificResource` holds it as its `source` (Cookbook 0045: a comment's words,
+ * given a `styleClass`). Caption files belong to the media transcript, so are left out.
+ * Light, for the Canvas's caption as well as the lists.
  */
 export interface AnnotationBodyEntry {
 	/** `TextualBody` text, as published: plain, or IIIF's limited HTML. */
@@ -62,8 +64,22 @@ export interface AnnotationBodyEntry {
 	language?: string;
 	/** An image body (Cookbook 0377): its URL. */
 	image?: string;
-	/** An image body's label, else its annotation's: the image's text alternative. */
+	/**
+	 * An image body's label, else its annotation's: the image's text alternative. A place's
+	 * name, its feature's `label`, else its annotation's.
+	 */
 	label?: LanguageMapLike;
+	/**
+	 * A place, a GeoJSON `Feature` (Cookbook 0139: a map on the page, tagged with where it
+	 * shows): named by its `label`, which the Map draws it under too.
+	 */
+	place?: true;
+	/**
+	 * One item of a `Choice` (Cookbook 0346: the same words in English and in Japanese), by
+	 * the choice's place among the annotation's: of each, one shows, the one in the reader's
+	 * language (`bodyInLanguage`, `core/annotation-name.ts`).
+	 */
+	choice?: number;
 }
 /**
  * Clover's one data shape: IIIF Presentation 4.
@@ -71,7 +87,8 @@ export interface AnnotationBodyEntry {
  * Every resource is upgraded to Presentation 4 on the way in, so no part is written for
  * several shapes. Presentation 2.1 and 3.0 are upgraded by `@iiif/parser`; Presentation 4
  * passes through untouched. The upgrader is imported on demand, so it costs nothing until
- * the first resource that needs it arrives.
+ * the first resource that needs it arrives, and its reader of Presentation 2 only with
+ * the first resource in 2.
  */
 export type Manifest = P4.Manifest;
 export type Presentation4Canvas = P4.Canvas;
@@ -85,7 +102,8 @@ export type Presentation4Timeline = P4.Timeline;
 export type Container = Presentation4Canvas | Presentation4Timeline | Presentation4Scene;
 /**
  * `resource` as Presentation 4: a Manifest, Collection, Canvas, Timeline or Scene from any
- * supported version. Presentation 4 input is returned as it is.
+ * supported version. Presentation 4 input is returned as it is; the rest is upgraded as
+ * `upgrade.ts` reads it, loaded with the upgrader.
  */
 export declare function toPresentation4<T = Manifest | Presentation4Collection | Container>(resource: unknown): Promise<T>;
 /**
@@ -108,12 +126,78 @@ export interface AnnotationEntry {
 	bodies: AnnotationBodyEntry[];
 	/** The annotation as published, for a host's own rendering. */
 	annotation: Record<string, any>;
+	/**
+	 * A Range's region (`range-regions.ts`): its place among the Range's parts, "1 of 4",
+	 * which its hotspot shows after its name.
+	 */
+	place?: {
+		index: number;
+		total: number;
+	};
+	/**
+	 * An annotation of one image of a `Choice` (Cookbook 0326: an X-ray's tag), not of the
+	 * Canvas: the choice's key (`core/choice-key.ts`), the item's place in it, and the
+	 * image's id. It is drawn while that item is the one chosen, and its `target` is given
+	 * here in the Canvas's terms, placed through the image's painting.
+	 */
+	layer?: {
+		key: string;
+		item: number;
+		image: string;
+	};
 }
+/**
+ * The set of the regions the Manifest's Ranges name (`range-regions.ts`), drawn as
+ * annotations, listed by Contents.
+ */
+export declare const CONTENTS_SET_ID = "contents";
 export interface AnnotationSet {
 	id: string;
 	label?: LanguageMapLike;
-	/** Where it came from: the Manifest's Canvases, the host, or a Content Search. */
-	source: "manifest" | "added" | "search";
+	/**
+	 * Where it came from: the Manifest's Canvases, the host, a Content Search, or the
+	 * regions the Manifest's Ranges name (`contentsSet`).
+	 */
+	source: "manifest" | "added" | "search" | "contents";
+	entries: AnnotationEntry[];
+	/** The AnnotationCollection its page is `partOf`, by id (Cookbook 0309). */
+	collection?: string;
+	/**
+	 * The AnnotationPage or AnnotationCollection it was given as, where it is the Root's
+	 * content (James Turner's tags across Manifests), walked as one whole.
+	 */
+	content?: {
+		id: string;
+		type: "AnnotationPage" | "AnnotationCollection";
+		label?: LanguageMapLike;
+	};
+}
+/** An annotation page a Canvas names: by id, its Canvas, and whether it is fetched. */
+export interface AnnotationPageRef {
+	id: string;
+	canvasId: string;
+	fetched: boolean;
+}
+/**
+ * Annotations walked as one whole, as a viewer walks a Collection's members: the
+ * AnnotationPage or AnnotationCollection given as the content (James Turner's tags across
+ * Manifests, all in hand), else an AnnotationCollection the Manifest's annotation pages
+ * are part of (Cookbook 0309: layout markup across a newspaper's pages, managed as one
+ * whole), whose pages load as the reader reaches them.
+ */
+export interface AnnotationCollection {
+	id: string;
+	type: "AnnotationPage" | "AnnotationCollection";
+	label?: LanguageMapLike;
+	/** The number of its annotations, where it says. */
+	total?: number;
+	/**
+	 * The Manifest's pages of it, in the Canvases' order, so a listing loads them as the
+	 * reader reaches them (`usePagesReached`, `clover.fetchAnnotationPages`). None for the
+	 * content's, whose annotations are all in hand.
+	 */
+	pages: AnnotationPageRef[];
+	/** Its annotations on the Manifest's Canvases, in their order, as far as fetched. */
 	entries: AnnotationEntry[];
 }
 /**
@@ -161,6 +245,34 @@ export interface Target {
 	/** Start playback on arrival (auto-advance from the previous Canvas). */
 	autoplay?: boolean;
 }
+/** One of a content state's several targets: a Manifest, and a place in it. */
+export interface ContentTarget {
+	/** Its own id: the content state's, with its place among the targets. */
+	id: string;
+	/** Where its Manifest is: the address it is loaded from. */
+	manifestId: string;
+	/**
+	 * The id its Manifest gives itself, once loaded, where it is not that address (Cookbook
+	 * 0540's are `…/manifest.json/manifest.json`, served at `…/manifest.json`).
+	 */
+	manifestAs?: string;
+	canvasId?: string;
+	/** In the Canvas's own coordinates. */
+	region?: {
+		x: number;
+		y: number;
+		w: number;
+		h: number;
+	};
+	/** Seconds into a time-based Canvas. */
+	time?: number;
+}
+/** A content state's targets, in its order, and its own `label` where it gives one. */
+export interface ContentTargets {
+	id: string;
+	label?: Record<string, string[]>;
+	items: ContentTarget[];
+}
 /** A content state as a link carries it: base64url of the URI-encoded JSON, unpadded. */
 export declare function encodeContentState(json: unknown): string;
 export interface ContentStateOutput {
@@ -170,13 +282,16 @@ export interface ContentStateOutput {
 	encoded: string;
 }
 /**
- * Where the reader is, as a content state: the Canvas within its Manifest, and the
- * visible region (`xywh=`) or the media time (`t=`) when there is one. Regions are
- * rounded to whole pixels.
+ * Where the reader is, as a content state: the Canvas (or Presentation 4's Timeline or
+ * Scene, by its `type`) within its Manifest, and the visible region (`xywh=`) or the
+ * media time (`t=`) when there is one. Regions are rounded to whole pixels. A Canvas
+ * shown on its own, outside a Manifest (one made around it carries its id, `loneCanvas`),
+ * is named without a `partOf`.
  */
-export declare function buildContentState({ manifestId, canvasId, region, time, }: {
-	manifestId: string;
+export declare function buildContentState({ manifestId, canvasId, type, region, time, }: {
+	manifestId?: string | null;
 	canvasId: string;
+	type?: string;
 	region?: {
 		x: number;
 		y: number;
@@ -273,6 +388,12 @@ export interface CloverState {
 	manifest: Manifest | null;
 	/** The Collection it was reached through, if any. */
 	collection: Presentation4Collection | null;
+	/**
+	 * Whether the content was that Collection (or a content state opening it): the Manifest
+	 * shown is one of its members, which the reader moves between. False for a Collection
+	 * read only from the Manifest's `partOf` (`openCollection`), and for no Collection.
+	 */
+	throughCollection: boolean;
 	/** The Canvas the reader is on: the first of the view that shows it. */
 	canvasId: string | null;
 	/** Where to go once the view is drawn: a region, a time. Consumed once applied. */
@@ -286,10 +407,28 @@ export interface CloverState {
 	 * drawn is `selectHiddenSets`'s.
 	 */
 	shownSets: string[];
-	/** Sets the host added through `annotations`, beside the Manifest's own. */
+	/**
+	 * Sets beside the Manifest's own pages: its images' own (Cookbook 0326, read once it is
+	 * shown, their module loaded then), the host's through `annotations`, and a content
+	 * state's note.
+	 */
 	addedSets: AnnotationSet[];
 	/** A Content Search of the Manifest: its query, progress and hits. */
 	search: SearchState;
+	/**
+	 * The regions the Manifest's Ranges name, as a set the Canvas draws (Cookbook 0025),
+	 * read once a Manifest whose Ranges name one is shown, its module loaded then; null
+	 * until then and for one without (`range-regions.ts`).
+	 */
+	regions: AnnotationSet | null;
+	/**
+	 * A content state's several targets (Cookbook 0540: two Canvases from two Manifests),
+	 * opened on the first, each to be gone to in turn (`goToTarget`); null for one target,
+	 * and for any other content. They stay through moves among them, until the next content.
+	 */
+	targets: ContentTargets | null;
+	/** The target last gone to: which one is current where two are on the same view. */
+	targetIndex: number | null;
 }
 export interface SearchState {
 	query: string;
@@ -337,6 +476,12 @@ export interface Clover {
 	highlight: Channel<string | null>;
 	/** The chapter (its Range's id) under the pointer on a seek bar, or in `Contents`. */
 	chapter: Channel<string | null>;
+	/**
+	 * The annotation the reader asked to find (`selectAnnotation`), each time they ask, the
+	 * one selected already among them: the Canvas frames it again, after the reader has
+	 * moved the view away (Cookbook 0021).
+	 */
+	found: Channel<string | null>;
 	readonly request: CloverRequest | undefined;
 	setRequest(request: CloverRequest | undefined): void;
 	/** Load content. `canvasId` wins over everything; `defaultCanvasId` over `start`. */
@@ -349,6 +494,12 @@ export interface Clover {
 	goToManifest(id: string, canvasId?: string): Promise<void>;
 	/** A controlled host's Manifest, shown without asking it again. */
 	syncManifest(id: string | null): Promise<void>;
+	/**
+	 * Go to one of a content state's targets (`state.targets`), by its place among them:
+	 * its Manifest opened where it is not the one shown (or the host asked, when it holds
+	 * the Manifest), then its Canvas, and its region or time.
+	 */
+	goToTarget(index: number): void;
 	/**
 	 * Show a Collection the Manifest is part of (its `partOf`) beside it: the Collection's
 	 * members become a choice, while the Manifest and the reader's place stay as they are.
@@ -394,6 +545,12 @@ export interface Clover {
 	 * `scope="all"`). Returns the release.
 	 */
 	holdAllAnnotationPages(): () => void;
+	/**
+	 * Fetch these referenced annotation pages, each once, wherever the Manifest's Canvases
+	 * name them: a listing that loads its pages as the reader reaches them (an
+	 * AnnotationCollection's, Cookbook 0309), rather than all at once.
+	 */
+	fetchAnnotationPages(pageIds: string[]): void;
 	/** Abandon any load in flight. The instance stays usable. */
 	dispose(): void;
 }
@@ -475,6 +632,14 @@ export interface RootProps extends Omit<React.HTMLAttributes<HTMLElement>, "chil
 	request?: CloverRequest;
 	/** The language to read IIIF text in. The reader's, by default. */
 	language?: string;
+	/**
+	 * Clover's higher-contrast mode, for every part inside: the accent kept to rings,
+	 * outlines and marks, and never under words or a glyph, where the controls' dark fill
+	 * takes its place, edged in the accent. For an accent that cannot carry white text at
+	 * 4.5:1. It is on wherever the reader's system asks for more contrast, too. Default
+	 * `false`.
+	 */
+	highContrast?: boolean;
 	/**
 	 * Renderers of your own for some views — by Canvas id, painting format, or a test —
 	 * drawn by every `Body` inside in place of `Canvas` (3.x's `customDisplays`).
@@ -491,8 +656,9 @@ export interface RootProps extends Omit<React.HTMLAttributes<HTMLElement>, "chil
 	 */
 	annotationPages?: "view" | "all";
 	/**
-	 * Where the reader is, as a IIIF content state, whenever it settles: after a move, a
-	 * pan or zoom, or a pause or seek in media. Debounced, and only when it changed.
+	 * Where the reader is, as a IIIF content state, as it changes: a move, a pan or zoom,
+	 * or a pause or seek in media. At most every 150ms while it moves, always its last
+	 * place, and only when it changed.
 	 */
 	onContentStateChange?: (state: ContentStateOutput) => void;
 	/** The element to render. Default `div`. */
@@ -564,6 +730,11 @@ export type CanvasRendererEvent =
  | "viewport"
 /** A new set of images replaced the previous one. */
  | "change" | "error"
+/**
+ * Whether nothing the scene paints could be loaded (its detail): every image failed to
+ * prepare, or every tile it wanted failed for good. Fires as that changes.
+ */
+ | "unloadable"
 /** The backend changed (fallback, or a context released and reacquired). */
  | "backend"
 /** A click that is not a zoom, with click-to-zoom turned off. */
@@ -717,6 +888,19 @@ export interface CanvasAnnotation {
 	pageLabel?: LanguageMapLike;
 	/** Its AnnotationPage's `id`, by which the menu hides its page (`hiddenPages`). */
 	pageId?: string;
+	/** A Range's region: its place among the Range's parts (`AnnotationEntry`'s). */
+	place?: {
+		index: number;
+		total: number;
+	};
+	/**
+	 * An annotation of one item of a `Choice` (Cookbook 0326): drawn while that item is the
+	 * one chosen, by the choice's key and the item's place (`AnnotationEntry`'s).
+	 */
+	layer?: {
+		key: string;
+		item: number;
+	};
 }
 /**
  * Everything a control needs in order to work, ready to spread onto a button: the id, the
@@ -786,6 +970,11 @@ export interface CanvasControlsConfig {
 	 * Shown only when a Canvas has either.
 	 */
 	information?: boolean;
+	/**
+	 * A map control that shows where the Canvas, else its Manifest, is (its `navPlace`), on a
+	 * map in a box, as the information is. Shown only when one of them has a place.
+	 */
+	map?: boolean;
 }
 export interface CloverCanvasOptions {
 	/** Which painter to use. `auto` (default) tries WebGL2, then Canvas2D. */
@@ -803,6 +992,7 @@ export interface CloverCanvasOptions {
 	 * stops moving, as the Player's `hideDelay`. Default 2000; `Infinity` keeps them once
 	 * shown. A finger, or a pen that does not hover, has no timer: a tap on the picture
 	 * shows them, and another hides them. Focus that no press brought holds them too.
+	 * A Timeline's: a Canvas's controls stay in sight, for now (Mat, 2026-11-01).
 	 */
 	hideDelay?: number;
 	/** A time-based Canvas's video or sound. */
@@ -907,6 +1097,13 @@ export interface CloverCanvasProps {
 	 * default; inside a `Root`, the Root's.
 	 */
 	language?: string;
+	/**
+	 * Clover's higher-contrast mode: the accent kept to rings, outlines and marks, and never
+	 * under words or a glyph, where the controls' dark fill takes its place, edged in the
+	 * accent. Inside a `Root`, the Root's too; on wherever the reader's system asks for more
+	 * contrast. Default `false`.
+	 */
+	highContrast?: boolean;
 	/** Stable id for this instance. A new id remounts the renderer. */
 	instanceId?: string;
 	className?: string;
@@ -924,6 +1121,14 @@ export interface CloverCanvasProps {
 	 * the handle `onReady` passes (`home()`, `zoomBy(0.5)`) (WCAG 2.5.1).
 	 */
 	controls?: boolean | CanvasControlsConfig;
+	/**
+	 * When the view's controls (zoom in and out, the two turns, reset, full screen)
+	 * collapse behind one button, at the end of the controls' one row, so the row fits any
+	 * width and leaves the media more room: `"auto"` (the default), only where the row
+	 * cannot hold them all; `"always"`, wherever the Canvas offers any, so the row holds
+	 * only the rest. Pressed, the button opens a tray of them beside the rest.
+	 */
+	collapseControls?: "auto" | "always";
 	/** Replace any control with your own component — the `Viewer`'s `controlButtons`. */
 	controlButtons?: ControlButtons;
 	/**
@@ -931,6 +1136,11 @@ export interface CloverCanvasProps {
 	 * targets are drawn; coordinates are the target image's own.
 	 */
 	annotations?: CanvasAnnotation[];
+	/**
+	 * The Manifest's `navPlace`, a GeoJSON FeatureCollection: where it is, which the map
+	 * control shows where the Canvases shown have none of their own.
+	 */
+	navPlace?: unknown;
 	/**
 	 * The AnnotationPages (each annotation's `pageId`) whose annotations are hidden: none
 	 * of them is drawn, but the annotations menu still lists them under their page, with
@@ -986,6 +1196,17 @@ export interface CloverCanvasProps {
 	manifestId?: string;
 	/** The visible world rectangle, at most once per frame while the camera moves. */
 	onViewportChange?: (bounds: Rect) => void;
+	/**
+	 * Where it is, as a IIIF content state, as it changes: as the Canvas changes, the
+	 * camera pans or zooms, or its media pauses or seeks. Both forms, the
+	 * annotation (`json`) and the same encoded for a URL (`encoded`); the Canvas, within its
+	 * Manifest (`manifestId`, the one it loaded, or its Root's), and the region in view or
+	 * the time. Of several shown together, it names the one filling most of the view.
+	 * Given `canvases`, it names no Manifest unless `manifestId` does; given only `src` or
+	 * `body`, it has no Canvas to name, and reports nothing. At most every 150ms while it
+	 * moves, always its last place, and only when it changed.
+	 */
+	onContentStateChange?: (state: ContentStateOutput) => void;
 	/**
 	 * A time-based Canvas's media element once it exists, and `null` when it goes: for a
 	 * host's own transcript, chapters or `#t=` seeks. Sound plays through a `<video>` too.
@@ -1023,6 +1244,12 @@ export interface CloverCanvasProps {
 		lang?: string;
 		start: number;
 		end?: number;
+		/**
+		 * A picture of it, over it on the seek bar and under it in the menu while it plays:
+		 * a URL, shown as it is, or a IIIF image (a Range's `thumbnail`), asked of its
+		 * service as its `info.json` allows. Inside a `Root`, its Range's `thumbnail`.
+		 */
+		thumbnail?: string | Record<string, unknown>;
 	}>;
 	/** A chapter (by its `id`) to mark on the seek bar, as hovering it in a list does. */
 	highlightedChapter?: string | null;
@@ -1057,7 +1284,7 @@ export type BodyProps = Omit<CloverCanvasProps, "canvases" | "body" | "src" | "i
  * shows Clover's loading mark, a line along its top edge, over what it still shows; it
  * keeps its size and its background, so nothing moves.
  */
-export declare function Body({ className, style, renderers, children, ...canvas }: BodyProps): React.JSX.Element;
+export declare function Body({ className, style, renderers, collapseControls, onContentStateChange, children, ...canvas }: BodyProps): React.JSX.Element;
 export interface LabelProps extends Omit<React.HTMLAttributes<HTMLElement>, "lang"> {
 	/** Whose label: the Manifest's (the default), or the current Canvas's. */
 	of?: "manifest" | "canvas";
@@ -1072,28 +1299,6 @@ export interface LabelProps extends Omit<React.HTMLAttributes<HTMLElement>, "lan
  * none.
  */
 export declare const Label: React.ForwardRefExoticComponent<LabelProps & React.RefAttributes<HTMLElement>>;
-/** What the pieces step through inside a Root: its views, or its Collection's members. */
-export type StepsOf = "views" | "members";
-export type ButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "children">;
-export interface StepProps extends ButtonProps {
-	/** What it steps through: the Root's views (default), or its Collection's members. */
-	of?: StepsOf;
-}
-/** Go to the previous item. `aria-disabled` on the first. */
-export declare const Previous: React.ForwardRefExoticComponent<StepProps & React.RefAttributes<HTMLButtonElement>>;
-/** Go to the next item. `aria-disabled` on the last. */
-export declare const Next: React.ForwardRefExoticComponent<StepProps & React.RefAttributes<HTMLButtonElement>>;
-export interface PositionProps extends React.HTMLAttributes<HTMLElement> {
-	/** What it counts: the Root's views (default), or its Collection's members. */
-	of?: StepsOf;
-	as?: React.ElementType;
-}
-/**
- * Where the reader is, counted in items: "2 / 5", the same in every language. Assistive
- * technology reads the sentence instead, "Item 2 of 5" in the reader's language, which a
- * bare slash would leave to guesswork.
- */
-export declare const Position: React.ForwardRefExoticComponent<PositionProps & React.RefAttributes<HTMLElement>>;
 /**
  * What `Items` shows: light models of a Manifest's views or a Collection's members, never
  * the resources themselves, so a long sequence costs a few fields per item.
@@ -1110,6 +1315,11 @@ export interface ItemPart {
 	duration?: number;
 	/** What it mostly paints: `Image`, `Video`, `Audio` (`Sound` in Presentation 3) or `Model`. */
 	media?: string;
+	/**
+	 * Its picture, where it is not the resource's own: a region of its Canvas (a content
+	 * state's target, Cookbook 0540). Null for none.
+	 */
+	source?: ThumbnailSource | null;
 }
 export interface ItemModel {
 	/** The first Canvas of a view, or a member's id. What selecting it goes to. */
@@ -1118,25 +1328,90 @@ export interface ItemModel {
 	parts: ItemPart[];
 	label?: LanguageMapLike;
 	summary?: LanguageMapLike;
+	/** A member's date for navigation, as written (Cookbook 0318). */
+	navDate?: string;
 	/** Where a link to a member goes: its `homepage`, else its id. */
 	href?: string;
+	/** That homepage's own language, where its `language` gives one. */
+	hrefLang?: string;
+}
+/** The line under an item's label: its summary, its date (`navDate`), or neither. */
+export type ItemSecondary = "summary" | "navDate" | "none";
+/**
+ * What the pieces step through inside a Root: its views, its Collection's members, or a
+ * content state's targets (Cookbook 0540).
+ */
+export type StepsOf = "views" | "members" | "targets";
+export interface PositionProps extends React.HTMLAttributes<HTMLElement> {
+	/** What it counts: the Root's views (default), or its Collection's members. */
+	of?: StepsOf;
+	as?: React.ElementType;
+}
+/**
+ * Where the reader is, counted in items: "2 / 5", the same in every language. Assistive
+ * technology reads the sentence instead, "Item 2 of 5" in the reader's language, which a
+ * bare slash would leave to guesswork.
+ */
+export declare const Position: React.ForwardRefExoticComponent<PositionProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Stepping through Items one at a time: `Previous`, `Next` and `Position`, and the three
+ * together as Items' `pager` layout (`<Clover.Items layout="pager" />`).
+ *
+ * They step through what Items lists: the Root's views (a paged book a spread at a time),
+ * or with `of="members"` the Collection's Manifests. The arrows follow the Manifest's
+ * `viewingDirection`: in a right-to-left book, "previous" points right. Each renders
+ * nothing when there is only one item.
+ *
+ * `Previous` and `Next` are round controls with an arrow, as Items' own arrows are: the
+ * name is hidden from sight but not from assistive technology, and shows on hover and
+ * focus. Where there is nowhere to go, each shows disabled.
+ *
+ * This module reads no thumbnails: a layout with a pager and no strip carries none of it.
+ * `Position` and the steps the three read are `Position.tsx`, which a page counting its
+ * views loads without the rest.
+ */
+export type ButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type" | "children">;
+export interface StepProps extends ButtonProps {
+	/** What it steps through: the Root's views (default), or its Collection's members. */
+	of?: StepsOf;
 }
+/** Go to the previous item. `aria-disabled` on the first. */
+export declare const Previous: React.ForwardRefExoticComponent<StepProps & React.RefAttributes<HTMLButtonElement>>;
+/** Go to the next item. `aria-disabled` on the last. */
+export declare const Next: React.ForwardRefExoticComponent<StepProps & React.RefAttributes<HTMLButtonElement>>;
 /**
- * A scrolling row of thumbnails (`slider`), a column, a wrapping grid, or one item at a
- * time (`pager`: Previous, Position and Next).
+ * A scrolling row of thumbnails (`slider`), a column, a wrapping grid, a grid whose
+ * pictures keep their proportions (`masonry`), or one item at a time (`pager`: Previous,
+ * Position and Next).
  */
-export type ItemsLayout = "slider" | "list" | "grid" | "pager";
+export type ItemsLayout = "slider" | "list" | "grid" | "masonry" | "pager";
 export interface ItemsProps extends Omit<React.HTMLAttributes<HTMLElement>, "onSelect" | "children"> {
 	/**
-	 * A scrolling row (the default), a column, a wrapping grid, or `pager`: Previous,
-	 * Position and Next, stepping one item at a time, with no thumbnails.
+	 * A scrolling row (the default), a column, a wrapping grid, `masonry`, or `pager`:
+	 * Previous, Position and Next, stepping one item at a time, with no thumbnails.
+	 * `masonry` is a grid whose pictures keep their own proportions, each item packed up
+	 * under the one above it, still in reading order, left to right.
 	 */
 	layout?: ItemsLayout;
 	/**
-	 * Inside a `Root`: the Manifest's views (default), or the members of the Collection it
-	 * belongs to, choosing one to show.
+	 * The line under an item's label, where it has one (a Collection's members do): its
+	 * `summary` (the default), its `navDate`, or `none`. Default `"summary"`.
+	 */
+	secondary?: ItemSecondary;
+	/**
+	 * The pager's size: `large` (the default), round controls; or `small`, its steps and
+	 * count as Search's are, for a header's line. Default `"large"`.
+	 */
+	size?: "large" | "small";
+	/**
+	 * Inside a `Root`: the Manifest's views (default), the members of the Collection it
+	 * belongs to, choosing one to show, a content state's targets, where it names two or
+	 * more (Cookbook 0540), each opening its Manifest at its place, or annotations walked as
+	 * one whole: the AnnotationPage or AnnotationCollection given as the content, else the
+	 * AnnotationCollection its annotation pages are part of (Cookbook 0309), each picked
+	 * and framed on its Canvas.
 	 */
-	of?: "views" | "members";
+	of?: "views" | "members" | "targets" | "annotations";
 	/**
 	 * Standalone: a Collection (its members), a Manifest (its views) or a URL to one. Inside
 	 * a `Root`, leave it out to list the Root's views.
@@ -1164,10 +1439,23 @@ export interface ItemsProps extends Omit<React.HTMLAttributes<HTMLElement>, "onS
 	headingLevel?: number;
 	/** Pixels requested for each thumbnail's longer side. Default 200. */
 	thumbnailSize?: number;
+	/**
+	 * Inside a `Root`: list the views even where there is only one, as a gallery's grid
+	 * does. The pager, with nothing to step to, still draws nothing. Default `false`: one
+	 * view has nothing to choose between.
+	 */
+	singleItem?: boolean;
 	/** Standalone: credentials, headers and `fetch`. In a `Root`, the Root's are used. */
 	request?: CloverRequest;
 	/** Standalone: the language to read IIIF text in. */
 	language?: string;
+	/**
+	 * Clover's higher-contrast mode: the accent kept to rings, outlines and marks, and never
+	 * under words or a glyph, where the controls' dark fill takes its place, edged in the
+	 * accent. Inside a `Root`, the Root's too; on wherever the reader's system asks for more
+	 * contrast. Default `false`.
+	 */
+	highContrast?: boolean;
 	/** Replace an item's figure with your own. */
 	renderItem?: (item: ItemModel, state: {
 		selected: boolean;
@@ -1378,8 +1666,17 @@ export interface PanelProps extends Omit<React.HTMLAttributes<HTMLElement>, "def
 	headingLevel?: number;
 	/** The element to render. Default `aside`. */
 	as?: React.ElementType;
-	/** Whether the default About lists the downloads (`About`'s `download`). Default `true`. */
+	/**
+	 * Whether About's heading offers the downloads, by a Download button that lists the
+	 * `rendering` of the page in view and of the Manifest. Default `true`.
+	 */
 	download?: boolean;
+	/**
+	 * Where what the resource says of itself comes in several languages, About's heading
+	 * offers them, and the whole Root reads in the one chosen. Default `true`; `false`
+	 * leaves the choice out, and the Root reads in its `language`, else the reader's.
+	 */
+	languages?: boolean;
 	/**
 	 * `Clover.Tab`s. Without any, the panel has the tabs Clover has data for: About,
 	 * Contents when the Manifest has Ranges, Search when it has a Content Search service, a
@@ -1411,7 +1708,11 @@ export interface AboutProps extends React.HTMLAttributes<HTMLElement> {
 	 * heading, and names its section instead (`ui/heading.ts`).
 	 */
 	headingLevel?: number;
-	/** List the downloads, Download's links, in a section of their own. Default `true`. */
+	/**
+	 * Alone, outside a Panel: list the downloads, Download's links, in a section of their
+	 * own. In a Panel, its heading's Download button lists them (the Panel's `download`).
+	 * Default `true`.
+	 */
 	download?: boolean;
 	/**
 	 * The Manifest's thumbnail first, small, at its own shape, floated at the end of the
@@ -1425,6 +1726,12 @@ export interface AboutProps extends React.HTMLAttributes<HTMLElement> {
 	 * it (Mat, 2026-10-26: "repeat label as a heading"). Default `true`.
 	 */
 	label?: boolean;
+	/**
+	 * Alone, outside a Panel: where what the resource says of itself comes in several
+	 * languages, offer them over what About says, the whole Root reading in the one chosen.
+	 * In a Panel, its heading offers them (the Panel's `languages`). Default `true`.
+	 */
+	languages?: boolean;
 }
 /**
  * Everything the Manifest says about itself, in the order 3.x's About tab shows it:
@@ -1434,8 +1741,12 @@ export interface AboutProps extends React.HTMLAttributes<HTMLElement> {
  * Each part renders only if the Manifest has
  * it. The downloads are Download's: the `rendering` of the page in view ("This page")
  * and of the Manifest ("All pages").
+ *
+ * Where what it says comes in several languages, the languages to read the resource in
+ * (`ReadingLanguages`): over what About says, or, in a Panel's `about` section, beside
+ * its heading, where they show whichever section is open.
  */
-export declare function About({ canvasSummary, headingLevel, download, thumbnail, label, className, ...rest }: AboutProps): React.JSX.Element | null;
+export declare function About({ languages, ...props }: AboutProps): React.JSX.Element;
 export interface AnnotationsProps extends React.HTMLAttributes<HTMLElement> {
 	/**
 	 * Every annotation in the Manifest (default), as the Viewer's panel lists them: by
@@ -1453,25 +1764,6 @@ export interface AnnotationsProps extends React.HTMLAttributes<HTMLElement> {
 	headingLevel?: number;
 	as?: React.ElementType;
 }
-/**
- * The annotations of the Root's resource — comments, tags, transcriptions — grouped by
- * set, as a list to read and to point with.
- *
- * - Each entry shows its content (IIIF's limited HTML, sanitized; an image body as an
- *   image). Pressing it frames the annotation on the Canvas, going to its Canvas first if
- *   need be. For the keyboard, a button inside it does the same, out of sight, its focus
- *   drawn around the entry.
- * - Hovering or focusing an entry highlights its hotspot, and hovering a hotspot
- *   highlights its entry: one highlight, shared through the Root, with no timers.
- * - Each set is headed by its AnnotationPage's own label, when it has one, and at the
- *   header's end a toggle that hides its annotations from the Canvas (`HideToggle`: an
- *   eye, "Hide" and the page's label, or "Hide annotations" for a page without one).
- *   Pointed at or focused, it lights every entry it hides.
- * - Where the same words come as separate annotations, one per language (a transcription
- *   and its translation), the set's header offers their languages by code ("AR", "EN"),
- *   and lists one at a time: the Root's `language` to start, else the reader's
- *   (`LanguageChoice`). Annotations in no language show whichever is chosen.
- */
 export declare const Annotations: React.ForwardRefExoticComponent<AnnotationsProps & React.RefAttributes<HTMLElement>>;
 export interface TranscriptProps extends React.HTMLAttributes<HTMLElement> {
 	as?: React.ElementType;
@@ -1508,7 +1800,10 @@ export interface TranscriptProps extends React.HTMLAttributes<HTMLElement> {
  * "IT") picks one: native radios, each named by its code and its file's label, in that
  * label's language. In an information panel's accordion the row sits beside the
  * Transcript's heading (`useSectionActions`), where it is not lost in the cues; elsewhere
- * it is over them.
+ * it is over them. The Root's language wins (Mat, 2026-10-28: "there should be one
+ * language toggle. always let root win"): the file in it is the one read, and where the
+ * Root offers the languages to read the resource in (`useReadingLanguages`), the
+ * Transcript offers none of its own.
  */
 export declare const Transcript: React.ForwardRefExoticComponent<TranscriptProps & React.RefAttributes<HTMLElement>>;
 export interface ContentsProps extends React.HTMLAttributes<HTMLElement> {
@@ -1517,7 +1812,17 @@ export interface ContentsProps extends React.HTMLAttributes<HTMLElement> {
 /**
  * The Manifest's table of contents, from its Ranges: chapters of a book, acts of an opera,
  * nested as they nest. The entry the reader is in is marked, following playback through a
- * time-based Canvas. Choosing an entry goes to its Canvas, and to its region or its moment.
+ * time-based Canvas. An entry with entries under it opens and closes them by a button at
+ * the end of its row (a disclosure, `aria-expanded`), named for it ("Sections in Act 1").
+ * They start closed, but for those holding the current entry: open from the root down
+ * to it, and set in the text's weight, so the trail to it shows (Mat, 2026-10-28). The
+ * reader's own choices hold, until the current entry comes into a branch it was not in,
+ * which opens. An article in parts (its columns, on pages out of order) has, while it is
+ * the current entry, a step through them in its row ("2 / 4", `ui/Steps`); its
+ * regions are drawn on the Canvas as annotations are (`range-regions.ts`). The current
+ * entry shows its Range's `thumbnail` (Cookbook 0229) under its words, large, as the seek
+ * bar's popover does, and the others none (`ui/EntryThumbnail`). Choosing an entry goes
+ * to its Canvas, and to its region or its moment.
  * Hovering or focusing one marks its chapter on the Canvas's seek bar, and the chapter
  * under the pointer there marks its entry here: one highlight, through the Root
  * (`clover.chapter`), as the annotations share theirs.
@@ -1534,7 +1839,9 @@ export interface DownloadProps extends Omit<React.HTMLAttributes<HTMLElement>, "
  * Downloads, as 3.x's Viewer offers them: the `rendering` of the Canvases in view ("This
  * page") and of the Manifest ("All pages") — a PDF, a text, a high-resolution file —
  * each a link, as Homepage lists a resource's pages (Mat, 2026-10-21: links, not a
- * button that opens them). Renders nothing when there is nothing to download.
+ * button that opens them). Pressed, a link saves its file rather than opening it, where
+ * its server lets the file be fetched (`saveFile`), and opens it in a new tab where not.
+ * Renders nothing when there is nothing to download.
  */
 export declare function Download({ className, headingLevel, ...rest }: DownloadProps): React.JSX.Element | null;
 /** A length: pixels as a number, or a CSS length in `px`, `rem` or `%` of the split. */
@@ -1700,7 +2007,7 @@ export declare function PanelToggle({ open, onOpenChange, controls, }: PanelTogg
  *   itself.
  */
 export declare const Canvas: React.FC<CloverCanvasProps>;
-export type TimelineProps = Omit<CloverCanvasProps, "canvases" | "body" | "src" | "isTiledImage" | "viewingDirection" | "navigator" | "onViewportChange" | "onReady" | "animateAnnotations"> & {
+export type TimelineProps = Omit<CloverCanvasProps, "canvases" | "body" | "src" | "isTiledImage" | "viewingDirection" | "navigator" | "collapseControls" | "onViewportChange" | "onReady" | "animateAnnotations"> & {
 	/**
 	 * A Presentation 4 Timeline to play: its sound, with what it carries (captions, a
 	 * transcript, annotations on its time, an accompanying or placeholder Canvas).
@@ -1763,6 +2070,13 @@ export interface SceneProps {
 	label?: unknown;
 	/** The language to read IIIF text in. The reader's, by default; inside a `Root`, the Root's. */
 	language?: string;
+	/**
+	 * Clover's higher-contrast mode: the accent kept to rings, outlines and marks, and never
+	 * under words or a glyph, where the controls' dark fill takes its place, edged in the
+	 * accent. Inside a `Root`, the Root's too; on wherever the reader's system asks for more
+	 * contrast. Default `false`.
+	 */
+	highContrast?: boolean;
 	className?: string;
 	/** All of Clover's controls (`true`, the default), none (`false`), or all but those set `false`. */
 	controls?: boolean | SceneControlsConfig;
@@ -1786,6 +2100,13 @@ export interface SceneProps {
 	 * rest, and sparse accessors, which Clover's does not draw yet.
 	 */
 	engine?: "clover" | "three";
+	/**
+	 * Where it is, as a IIIF content state, each time the Scene shown changes: the Scene
+	 * within its Manifest (`manifestId`, the one it loaded, or its Root's), as the
+	 * annotation (`json`) and the same encoded for a URL (`encoded`). A content state has no
+	 * camera to carry, so turning or zooming the models leaves it as it is.
+	 */
+	onContentStateChange?: (state: ContentStateOutput) => void;
 	/** Rendered after the controls in the cluster: a host's own controls. */
 	children?: React.ReactNode;
 }
@@ -1827,6 +2148,13 @@ export declare function useVisibleCanvases(): Container[];
 export declare function useActiveCanvas(): Container | null;
 /** Moving between views. Steps by view, so a spread moves two pages at a time. */
 export declare function useNavigation(): Navigation;
+/**
+ * Annotations walked as one whole: the AnnotationPage or AnnotationCollection given as
+ * the content, else the AnnotationCollection the Manifest's annotation pages are part of
+ * (Cookbook 0309). Its `id`, `type`, `label`, `total`, `pages` and its annotations so far
+ * (`entries`); null where there are none. `Items of="annotations"` walks them.
+ */
+export declare function useAnnotationCollection(): AnnotationCollection | null;
 /** Every annotation set: the Manifest's own (fetched so far) and any the host added. */
 export declare function useAnnotationSets(): AnnotationSet[];
 /** A IIIF language map as text in the Root's language, with the tag it is in. */
@@ -1869,7 +2197,7 @@ export interface Shortcut {
  * hides it without moving the pointer or focus; the pointer can move onto it without it
  * closing; and it stays until the pointer or focus leaves. Styles are `ui/Tip.css`.
  */
-export declare function Tip({ label, lang, shortcut, scrolls, image, }: {
+export declare function Tip({ label, lang, shortcut, scrolls, image, lead, after, }: {
 	label: string;
 	/** The language of `label`, where it is not its control's. */
 	lang?: string;
@@ -1885,6 +2213,18 @@ export declare function Tip({ label, lang, shortcut, scrolls, image, }: {
 	 * shows, and named by them, as the control is.
 	 */
 	image?: string;
+	/**
+	 * A line over the words, set apart from them: the time under the pointer, over a
+	 * chapter's title in the seek bar's popover (`ui/Tip.css`). Shown only: its control
+	 * says it for assistive technology.
+	 */
+	lead?: string;
+	/**
+	 * A figure after the words, smaller, as the step through a list sets its place (a
+	 * Range's region's "1 / 4", `ui/Steps.css`). Shown only: its control says it for
+	 * assistive technology.
+	 */
+	after?: React.ReactNode;
 }): React.JSX.Element;
 /**
  * Clover's popups open one at a time: the Canvas's menus (annotations, Choice, an
@@ -1962,6 +2302,11 @@ export declare function titled(level: number, id: string, fallback?: React.Eleme
 export interface CloverContextValue {
 	clover: Clover;
 	language?: string;
+	/**
+	 * The reader chose a language to read IIIF text in (About's languages): every part
+	 * inside reads in it, until the Root is given another `language`.
+	 */
+	chooseLanguage?: (tag: string) => void;
 	/** Renderers of the host's own, for `Body` to draw some views with. */
 	renderers?: BodyRenderer[];
 }
@@ -2006,6 +2351,11 @@ export interface Chapter {
 	label?: LanguageMapLike;
 	start: number;
 	end?: number;
+	/**
+	 * Its Range's `thumbnail` (Cookbook 0229), the first it gives, as written: what draws
+	 * it asks its service as its `info.json` allows (`ui/EntryThumbnail`).
+	 */
+	thumbnail?: Record<string, unknown>;
 }
 export declare function chaptersOf(manifest: Manifest | null, canvasId: string | null, duration?: number): Chapter[];
 /** One entry of a table of contents: a Range, where it starts, and the Ranges within. */
@@ -2028,8 +2378,33 @@ export interface ContentsNode {
 		w: number;
 		h: number;
 	};
+	/**
+	 * Its own Canvases and their parts, in the order the Range reads them (Cookbook 0025:
+	 * an article's columns, page 2 then page 5): for a `sequence` (Cookbook 0027), where a
+	 * region is among them, which the Canvas draws (`range-regions.ts`), or where its pages
+	 * are out of the Manifest's order; two or more are stepped through in Contents. None on
+	 * a recording's time, nor for any other run of whole pages in order, which Items steps.
+	 */
+	parts?: ContentsPart[];
+	/**
+	 * A Range of `behavior` `sequence` (Cookbook 0027): an order of the Canvases of its own,
+	 * the first of them the default, as `currentContents` takes it.
+	 */
+	sequence?: true;
+	/** Its Range's `thumbnail` (Cookbook 0229), the first it gives, as written. */
+	thumbnail?: Record<string, unknown>;
 	children: ContentsNode[];
 }
+/** One Canvas, or a region of one, in a Range's reading order. */
+export interface ContentsPart {
+	canvasId: string;
+	region?: {
+		x: number;
+		y: number;
+		w: number;
+		h: number;
+	};
+}
 /**
  * The Manifest's table of contents, from `structures`. A single top Range that only wraps
  * others is unwrapped, as a reader expects its chapters, not one entry holding them.
@@ -2040,7 +2415,12 @@ export declare function tableOfContents(manifest: Manifest | null): ContentsNode
  * The entry the reader is in: the deepest covering `canvasId` whose span holds `time` (or
  * that has no span). Null when none is.
  */
-export declare function currentContents(nodes: ContentsNode[], canvasId: string | null, time?: number): string | null;
+export declare function currentContents(nodes: ContentsNode[], canvasId: string | null, time?: number, 
+/**
+ * The entry the reader chose: it, or the deepest entry in it, is current wherever it
+ * covers the Canvas and time, over any other that does (one of two sequences).
+ */
+chosen?: string | null): string | null;
 export declare function toPlainText(html: string): string;
 /**
  * How a text is read, strictly by its `format`'s media type: `text/html` as IIIF's HTML,
@@ -2056,14 +2436,16 @@ export declare function readAs(format: string | undefined, value?: string): "mar
  * there is found, and the region read as shares of it (scaled from where it is painted),
  * so the service's own `info.json` decides how it is asked for, never more than the
  * region has, and from a server that cannot cut a region, nothing (no fallback: all of
- * the image is not the region). Null where no image with a service is painted there.
+ * the image is not the region). A `Choice`'s first image stands for it, or the one named
+ * (`image`: a layer's annotation is cut from its own layer, Cookbook 0326). Null where no
+ * image with a service is painted there.
  */
 export declare function regionSource(canvas: Json | undefined, rect: {
 	x: number;
 	y: number;
 	w: number;
 	h: number;
-}): ThumbnailSource | null;
+}, image?: string): ThumbnailSource | null;
 /**
  * Clover's translations, without a translation library.
  *
@@ -2159,10 +2541,20 @@ export type DefaultProps = Omit<RootProps, "children"> & {
 	 * stacked boxes each opened by its heading, or `"tabs"`.
 	 */
 	panelLayout?: PanelLayout;
-	/** The downloads in the panel's About, as links. Default `true`. */
+	/** The downloads, from a Download button beside the panel's About heading. Default `true`. */
 	download?: boolean;
+	/**
+	 * The languages to read the resource in, beside the panel's About heading, where what
+	 * it says of itself comes in several (the Panel's `languages`). Default `true`.
+	 */
+	languages?: boolean;
 	/** The thumbnails under the Body: a layout, or `false` for none. Default `slider`. */
 	items?: Exclude<ItemsLayout, "pager"> | false;
+	/**
+	 * The thumbnails even where the resource has one view, which has nothing to choose
+	 * between. Default `false`.
+	 */
+	singleItem?: boolean;
 	/**
 	 * Where the panel's width is remembered once the reader drags its bar
 	 * (`localStorage`). Default `"clover-template-default"`; `false` forgets it.
@@ -2175,8 +2567,14 @@ export type DefaultProps = Omit<RootProps, "children"> & {
 	 * `--clover-body-height` tall, and the layout as tall as it needs.
 	 */
 	fill?: boolean;
+	/**
+	 * When the Body's view controls (zoom, the turns, reset, full screen) wait behind
+	 * More: `"auto"` (the default), only where its row cannot hold them all; `"always"`.
+	 * The Body's `collapseControls`.
+	 */
+	collapseControls?: "auto" | "always";
 };
-declare function Default({ className, header, headingLevel, panel, defaultPanelOpen, panelLayout, download, items, storageKey, fill, ...root }: DefaultProps): React.JSX.Element;
+declare function Default({ className, header, headingLevel, panel, defaultPanelOpen, panelLayout, download, languages, items, singleItem, storageKey, fill, collapseControls, ...root }: DefaultProps): React.JSX.Element;
 /**
  * A layout the Viewer draws: one from `@nulib/clover/templates`, or a component of your
  * own that takes the `Clover.Root` props.