@ikaros-arch/react-3dhop-iiif 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,808 @@
+import React from 'react';
+import { ModelDefinition, SceneSpaceConfig, SceneRenderConfig, TrackballConfig, ThreeDHopViewerProps } from '@ikaros-arch/react-3dhop';
+
+/**
+ * Types for the subset of IIIF Presentation API 4.0 / IIIF 3D that this package understands.
+ *
+ * The raw `IIIF*` types describe manifest JSON as authored. The `Parsed*` types describe the
+ * normalised, viewer-ready shape the parser produces.
+ */
+/** An IIIF language map: BCP-47 tag → one or more strings. May also appear as a bare string. */
+type LanguageMap = Record<string, string | string[]>;
+type LocalizableValue = LanguageMap | string;
+type Vector3 = [number, number, number];
+type IIIFMetadataEntry = {
+    label?: LocalizableValue;
+    value?: LocalizableValue;
+};
+type IIIFPointSelector = {
+    type?: 'PointSelector' | string;
+    x?: number;
+    y?: number;
+    z?: number;
+};
+type IIIFTransform = {
+    type?: 'ScaleTransform' | 'TranslateTransform' | 'RotateTransform' | string;
+    x?: number;
+    y?: number;
+    z?: number;
+    /** Single axis-angle form: `{ type: 'RotateTransform', axis: 'y', angle: 45 }`. */
+    axis?: 'x' | 'y' | 'z' | string;
+    angle?: number;
+};
+type IIIFModelSource = {
+    id?: string;
+    type?: 'Model' | string;
+    format?: string;
+    /** Non-standard extension: the unit the model's own coordinates are expressed in. */
+    measureUnit?: string;
+};
+type IIIFAnnotationBody = {
+    id?: string;
+    type?: string;
+    label?: LocalizableValue;
+    format?: string;
+    measureUnit?: string;
+    source?: IIIFModelSource | IIIFModelSource[];
+    transform?: IIIFTransform[];
+    /** Camera-only fields. */
+    fieldOfView?: number;
+    fov?: number;
+    lookAt?: IIIFPointSelector & {
+        id?: string;
+    };
+};
+type IIIFAnnotationTarget = {
+    type?: string;
+    source?: unknown;
+    selector?: IIIFPointSelector | IIIFPointSelector[];
+};
+type IIIFAnnotation = {
+    id?: string;
+    type?: string;
+    motivation?: string | string[];
+    label?: LocalizableValue;
+    body?: IIIFAnnotationBody | IIIFAnnotationBody[];
+    target?: IIIFAnnotationTarget | IIIFAnnotationTarget[] | string;
+};
+type IIIFAnnotationPage = {
+    id?: string;
+    type?: string;
+    items?: IIIFAnnotation[];
+};
+type IIIFScene = {
+    id?: string;
+    type?: string;
+    label?: LocalizableValue;
+    items?: IIIFAnnotationPage[];
+};
+type IIIFManifest = {
+    id?: string;
+    type?: string;
+    label?: LocalizableValue;
+    summary?: LocalizableValue;
+    requiredStatement?: {
+        label?: LocalizableValue;
+        value?: LocalizableValue;
+    };
+    metadata?: IIIFMetadataEntry[];
+    items?: IIIFScene[];
+};
+type ParsedModel = {
+    /** The annotation id, used as the stable key for this instance. */
+    id: string;
+    /** Raw language map for the annotation label; resolve with the active language. */
+    rawLabel?: LocalizableValue;
+    url: string;
+    format?: string;
+    /** Unit for this model specifically; falls back to the manifest's `MEASURE_UNIT`. */
+    measureUnit?: string;
+    /** World-space placement from the target `PointSelector`. */
+    position: Vector3;
+    /** The manifest's `transform` list, in authored order. */
+    transforms: IIIFTransform[];
+};
+type ParsedCamera = {
+    id?: string;
+    type: 'PerspectiveCamera' | 'OrthographicCamera';
+    rawLabel?: LocalizableValue;
+    position: Vector3;
+    /** Field of view in degrees, when the manifest specifies one. */
+    fov?: number;
+    /** Explicit look-at point, when `lookAt` carries coordinates. */
+    target?: Vector3;
+    /** Annotation id the camera looks at, when `lookAt` is a reference. */
+    lookAtId?: string;
+};
+/**
+ * Manifest-level metadata. The five `knownFields` are recognised by label (in English or
+ * Norwegian) and lifted out; everything else is kept verbatim in `fields`, in manifest order.
+ */
+type ParsedMetadata = {
+    label: string;
+    summary?: string;
+    attribution?: string;
+    museum?: string;
+    inventory?: string;
+    objectId?: string;
+    /** Unit the manifest's coordinates are authored in. Defaults to `mm` downstream. */
+    measureUnit?: string;
+    /** Unit the viewer should present measurements in. Defaults to `measureUnit` downstream. */
+    displayUnit?: string;
+    /** Every metadata entry, including the recognised ones, resolved into the active language. */
+    fields: Array<{
+        label: string;
+        value: string;
+    }>;
+};
+type ParsedManifest = {
+    manifest: IIIFManifest;
+    metadata: ParsedMetadata;
+    models: ParsedModel[];
+    cameras: ParsedCamera[];
+    /** Every language tag appearing anywhere in the manifest's language maps. */
+    languages: string[];
+};
+/** A world-space camera, the intermediate form between IIIF and the 3DHOP trackball. */
+type View = {
+    position: Vector3;
+    target: Vector3;
+    up: Vector3;
+    /** Degrees; `0` denotes an orthographic camera. */
+    fov: number;
+};
+/** Non-fatal notes emitted while parsing — unknown formats, skipped annotations, and so on. */
+type Diagnostic = {
+    level: 'info' | 'warning';
+    message: string;
+};
+type DiagnosticHandler = (diagnostic: Diagnostic) => void;
+type IIIFThumbnail = {
+    id: string;
+    type?: string;
+    format?: string;
+};
+type IIIFCollectionItem = {
+    id: string;
+    type?: 'Manifest' | string;
+    label?: LocalizableValue;
+    summary?: LocalizableValue;
+    thumbnail?: IIIFThumbnail | IIIFThumbnail[];
+};
+type IIIFCollection = {
+    id?: string;
+    type?: 'Collection' | string;
+    label?: LocalizableValue;
+    summary?: LocalizableValue;
+    items?: IIIFCollectionItem[];
+};
+type ParsedCollectionItem = {
+    id: string;
+    label: string;
+    summary?: string;
+    /** URL of the first thumbnail image, when the item has one. */
+    thumbnail?: string;
+};
+type ParsedCollection = {
+    collection: IIIFCollection;
+    label: string;
+    summary?: string;
+    items: ParsedCollectionItem[];
+};
+
+/** Unit assumed when a manifest declares none. Matches the original viewer's behaviour. */
+declare const DEFAULT_MEASURE_UNIT = "mm";
+type SceneFromManifest = {
+    models: Record<string, ModelDefinition>;
+    space: SceneSpaceConfig;
+    config: SceneRenderConfig;
+    trackball: TrackballConfig;
+    /** The unit the scene's coordinates are now in — what measurements should be labelled with. */
+    displayUnit: string;
+    measureUnit: string;
+    /** Maps each generated instance key back to the IIIF annotation it came from. */
+    instanceIdsByModelId: Record<string, string>;
+};
+type ToModelsOptions = {
+    /** Overrides the manifest's `display unit` metadata. */
+    displayUnit?: string;
+    /** Merged over the defaults derived from the manifest. */
+    space?: SceneSpaceConfig;
+    config?: SceneRenderConfig;
+    trackball?: TrackballConfig;
+};
+/**
+ * Translates a parsed manifest into the props `<ThreeDHopViewer>` needs.
+ *
+ * Models sharing a source URL are collapsed onto a single mesh, so a manifest that places the same
+ * object several times downloads it once.
+ */
+declare function sceneFromManifest(parsed: ParsedManifest, options?: ToModelsOptions): SceneFromManifest;
+
+type IIIFViewerProps = Omit<ThreeDHopViewerProps, 'models' | 'modelUrl'> & {
+    /** A manifest URL to fetch, or an already-fetched manifest object. */
+    manifest: string | IIIFManifest;
+    /** Language used for labels and metadata. Defaults to the browser's, falling back to `'en'`. */
+    language?: string;
+    /** Overrides the manifest's `display unit`, changing the scale the scene is rendered at. */
+    displayUnit?: string;
+    /** Applies the manifest's first camera as the initial view once the scene is ready. */
+    applyInitialCamera?: boolean;
+    onLoad?: (parsed: ParsedManifest, scene: SceneFromManifest) => void;
+    onError?: (error: Error) => void;
+    onDiagnostic?: (diagnostic: Diagnostic) => void;
+    /** Rendered instead of the viewer while the manifest is being fetched. */
+    loadingFallback?: React.ReactNode;
+    /** Rendered instead of the viewer when the manifest cannot be loaded or parsed. */
+    errorFallback?: React.ReactNode | ((error: Error) => React.ReactNode);
+};
+/**
+ * Renders a IIIF 3D manifest with 3DHOP.
+ *
+ * Fetches and parses the manifest, derives the scene, and makes the result available to any
+ * descendant through `useIIIFManifest()`. Everything `<ThreeDHopViewer>` accepts can be passed
+ * through, except the model props this component supplies itself.
+ */
+declare const IIIFViewer: React.FC<IIIFViewerProps>;
+
+type ManifestSceneEntry = {
+    /** Sanitized id for this manifest, unique within the merged scene. Used to namespace model keys
+     *  and to disambiguate per-manifest visibility/transparency state. */
+    key: string;
+    /** The manifest's own id/URL, kept for display/debugging. */
+    sourceId: string;
+    parsed: ParsedManifest;
+    /** `parsed.models`, unmodified — for panels that need per-model metadata/labels. */
+    models: ParsedModel[];
+    /** IIIF annotation id -> globally-unique instance key in the merged `models` record. */
+    instanceIdsByModelId: Record<string, string>;
+    /** World-space offset applied to every model belonging to this manifest, in the shared displayUnit. */
+    offset: Vector3;
+    /** Placement-spread radius used to compute `offset`. Exposed for debugging/tests. */
+    layoutRadius: number;
+};
+type SceneFromManifests = {
+    models: Record<string, ModelDefinition>;
+    space: SceneSpaceConfig;
+    config: SceneRenderConfig;
+    trackball: TrackballConfig;
+    displayUnit: string;
+    measureUnit: string;
+    manifests: ManifestSceneEntry[];
+};
+type ToMultiModelsOptions = {
+    /** Shared display unit every manifest is converted into. Defaults to the first manifest's. */
+    displayUnit?: string;
+    space?: SceneSpaceConfig;
+    config?: SceneRenderConfig;
+    trackball?: TrackballConfig;
+    /** Gap kept between adjacent manifests' layout circles, in the shared displayUnit. Default 50. */
+    gap?: number;
+    /**
+     * Floor applied to every manifest's placement-spread radius.
+     *
+     * There is no real mesh geometry size available at this point — meshes stream in later, and the
+     * manifest only tells us where each annotation is *placed*, not how big it is. Most manifests
+     * place a single model at the origin, which has a spread of 0; without this floor every such
+     * manifest would land on top of the others. Tune this per dataset. Default 100.
+     */
+    minRadius?: number;
+    /** Manifests per row before wrapping onto a new row. Default: unlimited (single row). */
+    columns?: number;
+    /** Escape hatch: an explicit offset per manifest key, skipping automatic layout for that manifest. */
+    layoutOverrides?: Record<string, Vector3>;
+};
+/**
+ * Arranges circles of the given radii on the X/Z plane, packed left-to-right and wrapped every
+ * `columns` entries, each separated by `gap`. Returns one offset per input radius, re-centred so
+ * the layout's bounding box sits on the origin (cosmetic only — `centerMode: 'scene'` reframes the
+ * camera around the actual rendered geometry regardless).
+ */
+declare function layoutManifests(radii: number[], options: {
+    gap: number;
+    columns: number;
+}): Vector3[];
+/**
+ * Translates several parsed manifests into the props `<ThreeDHopViewer>` needs for a single,
+ * combined scene — one manifest per `ParsedManifest`, laid out side by side so their models don't
+ * overlap even when their native coordinates coincide (see {@link ToMultiModelsOptions.minRadius}).
+ *
+ * Delegates all per-manifest unit conversion and matrix building to {@link sceneFromManifest}, then
+ * re-keys and offsets the result so it can be merged into one flat model dictionary.
+ */
+declare function sceneFromManifests(parsedList: ParsedManifest[], sourceIds: string[], options?: ToMultiModelsOptions): SceneFromManifests;
+
+type IIIFMultiManifestViewerProps = Omit<ThreeDHopViewerProps, 'models' | 'modelUrl'> & {
+    /** Manifest URLs to fetch, or already-fetched manifest objects, in display order. */
+    manifests: Array<string | IIIFManifest>;
+    /** Language used for labels. Defaults to the browser's, falling back to `'en'`. */
+    language?: string;
+    /** Overrides every manifest's `display unit`, converting them all onto one shared scale. */
+    displayUnit?: string;
+    /** Gap kept between adjacent manifests' layout circles, in the shared displayUnit. */
+    gap?: number;
+    /** Floor applied to every manifest's placement-spread radius. See `ToMultiModelsOptions.minRadius`. */
+    minRadius?: number;
+    /** Manifests per row before wrapping onto a new row. */
+    columns?: number;
+    /** Escape hatch: an explicit offset per manifest key, skipping automatic layout for that manifest. */
+    layoutOverrides?: Record<string, Vector3>;
+    onLoad?: (scene: SceneFromManifests) => void;
+    /** Fired once per manifest that fails to load or parse. */
+    onError?: (error: Error, sourceId: string) => void;
+    onDiagnostic?: (diagnostic: Diagnostic) => void;
+    /** Rendered instead of the viewer while the manifests are being fetched. */
+    loadingFallback?: React.ReactNode;
+    /** Rendered instead of the viewer when any manifest cannot be loaded or parsed. */
+    errorFallback?: React.ReactNode | ((errors: Array<{
+        sourceId: string;
+        error: Error;
+    }>) => React.ReactNode);
+};
+/**
+ * Renders several IIIF 3D manifests together in one 3DHOP viewer, laid out side by side.
+ *
+ * A parallel component to `<IIIFViewer>` rather than an extension of it: this scene is a merge of
+ * N independently-fetched manifests, and fails fast if any one of them can't be loaded — a mix of
+ * "some succeeded, some didn't" isn't a state a shared scene can represent cleanly for v1.
+ */
+declare const IIIFMultiManifestViewer: React.FC<IIIFMultiManifestViewerProps>;
+
+type IIIFStatus = 'idle' | 'loading' | 'ready' | 'error';
+type IIIFContextValue = {
+    status: IIIFStatus;
+    error: Error | null;
+    /** Non-fatal notes collected while parsing, in the order they were emitted. */
+    diagnostics: Diagnostic[];
+    parsed: ParsedManifest | null;
+    metadata: ParsedMetadata | null;
+    models: ParsedModel[];
+    cameras: ParsedCamera[];
+    languages: string[];
+    language: string;
+    setLanguage: (language: string) => void;
+    /** Resolves any language map from the manifest into the active language. */
+    localize: (value: LocalizableValue | undefined) => string;
+    measureUnit: string;
+    displayUnit: string;
+    /**
+     * Whether the presenter has established the scene's centre and radius. Camera operations are
+     * no-ops until this is true, because there is nothing to convert against yet.
+     */
+    isSceneReady: boolean;
+    /** Animates the camera to the manifest camera at `index`. */
+    goToCamera: (index: number, durationSeconds?: number) => void;
+    /** Captures the current camera as an IIIF annotation, or `null` if the scene is not ready. */
+    saveCurrentView: (label?: string) => Record<string, unknown> | null;
+    /** Shows or hides one model. Pass the IIIF annotation id. */
+    setModelVisible: (modelId: string, visible: boolean) => void;
+    isModelVisible: (modelId: string) => boolean;
+    toggleModelTransparency: (modelId: string) => void;
+    isModelTransparent: (modelId: string) => boolean;
+};
+/** Access the IIIF manifest state. Must be called from inside an `<IIIFViewer>`. */
+declare function useIIIFManifest(): IIIFContextValue;
+type IIIFProviderProps = {
+    status: IIIFStatus;
+    error: Error | null;
+    diagnostics: Diagnostic[];
+    parsed: ParsedManifest | null;
+    scene: SceneFromManifest | null;
+    language: string;
+    setLanguage: (language: string) => void;
+    children?: React.ReactNode;
+};
+/**
+ * Supplies IIIF state to descendants and bridges it to the live presenter.
+ *
+ * Rendered inside `<ThreeDHopViewer>` so it can reach the viewer context, which is the only place
+ * the presenter — and with it the scene framing that camera conversion needs — is available.
+ */
+declare const IIIFProvider: React.FC<IIIFProviderProps>;
+
+type IIIFMultiManifestStatus = 'idle' | 'loading' | 'ready' | 'error';
+type ManifestGroup = {
+    /** Unique within this scene. Pass to the `manifestKey` argument of the accessors below. */
+    key: string;
+    sourceId: string;
+    label: string;
+    models: ParsedModel[];
+};
+type IIIFMultiManifestContextValue = {
+    status: IIIFMultiManifestStatus;
+    error: Error | null;
+    diagnostics: Diagnostic[];
+    manifests: ManifestGroup[];
+    measureUnit: string;
+    displayUnit: string;
+    /** Whether the presenter has established the scene, so instance toggles have something to act on. */
+    isSceneReady: boolean;
+    /** Shows or hides one model. `modelId` is the IIIF annotation id, scoped to `manifestKey`. */
+    setModelVisible: (manifestKey: string, modelId: string, visible: boolean) => void;
+    isModelVisible: (manifestKey: string, modelId: string) => boolean;
+    toggleModelTransparency: (manifestKey: string, modelId: string) => void;
+    isModelTransparent: (manifestKey: string, modelId: string) => boolean;
+};
+/** Access the multi-manifest scene state. Must be called from inside an `<IIIFMultiManifestViewer>`. */
+declare function useIIIFMultiManifest(): IIIFMultiManifestContextValue;
+type IIIFMultiManifestProviderProps = {
+    status: IIIFMultiManifestStatus;
+    error: Error | null;
+    diagnostics: Diagnostic[];
+    scene: SceneFromManifests | null;
+    children?: React.ReactNode;
+};
+/**
+ * Supplies multi-manifest scene state to descendants and bridges it to the live presenter.
+ *
+ * A deliberately smaller sibling of `<IIIFProvider>`: cameras, saved views, metadata and language
+ * are per-manifest concepts that don't yet have a defined multi-manifest behaviour, so this only
+ * covers per-model visibility/transparency, each scoped by the manifest it came from.
+ */
+declare const IIIFMultiManifestProvider: React.FC<IIIFMultiManifestProviderProps>;
+
+type IIIFCollectionStatus = 'idle' | 'loading' | 'ready' | 'error';
+type IIIFCollectionContextValue = {
+    status: IIIFCollectionStatus;
+    error: Error | null;
+    diagnostics: Diagnostic[];
+    label: string;
+    summary: string | null;
+    items: ParsedCollectionItem[];
+    /** id of the manifest currently selected, e.g. to pass straight into `<IIIFViewer manifest={...}>`. */
+    selectedId: string | null;
+    selectedIndex: number;
+    selectedItem: ParsedCollectionItem | null;
+    selectManifest: (id: string) => void;
+    next: () => void;
+    previous: () => void;
+};
+/** Access the IIIF collection state. Must be called from inside an `<IIIFCollectionProvider>`. */
+declare function useIIIFCollection(): IIIFCollectionContextValue;
+type IIIFCollectionProviderProps = {
+    /** A collection URL to fetch, or an already-fetched collection object. */
+    collection: string | IIIFCollection;
+    /** Language used for item labels. Defaults to `'en'`. */
+    language?: string;
+    /** Selects this manifest id once the collection loads, instead of the first item. */
+    initialManifestId?: string;
+    onLoad?: (items: ParsedCollectionItem[]) => void;
+    onError?: (error: Error) => void;
+    onDiagnostic?: (diagnostic: Diagnostic) => void;
+    children?: React.ReactNode;
+};
+/**
+ * Fetches and parses a IIIF Collection, and tracks which of its manifests is selected.
+ *
+ * Unlike `<IIIFViewer>`, this renders nothing itself — it only supplies `useIIIFCollection()` to
+ * descendants, such as `<IIIFCollectionPicker>`, `<IIIFCollectionCarousel>`, and the `<IIIFViewer>`
+ * that should render `selectedId`. Keeping it separate lets the collection state outlive remounts
+ * of the viewer (e.g. `key={selectedId}`) that discard camera and visibility state per manifest.
+ */
+declare const IIIFCollectionProvider: React.FC<IIIFCollectionProviderProps>;
+
+type IIIFCollectionPickerProps = {
+    label?: React.ReactNode;
+    emptyMessage?: React.ReactNode;
+    className?: string;
+    labelClassName?: string;
+    selectClassName?: string;
+};
+/** A `<select>` of every manifest in the collection. Pass the selected id straight to `<IIIFViewer>`. */
+declare const IIIFCollectionPicker: React.FC<IIIFCollectionPickerProps>;
+
+type IIIFCollectionCarouselProps = {
+    previousLabel?: string;
+    nextLabel?: string;
+    emptyMessage?: React.ReactNode;
+    className?: string;
+    trackClassName?: string;
+    itemClassName?: string;
+    activeItemClassName?: string;
+    thumbnailClassName?: string;
+    labelClassName?: string;
+    controlClassName?: string;
+};
+/** A scrollable strip of thumbnails, one per manifest in the collection, with prev/next controls. */
+declare const IIIFCollectionCarousel: React.FC<IIIFCollectionCarouselProps>;
+
+type IIIFSummaryProps = {
+    className?: string;
+    summaryClassName?: string;
+    attributionClassName?: string;
+};
+/**
+ * The manifest's `summary` and the attribution from its `requiredStatement`.
+ *
+ * Renders nothing when the manifest supplies neither.
+ */
+declare const IIIFSummary: React.FC<IIIFSummaryProps>;
+
+type IIIFMetadataPanelProps = {
+    heading?: React.ReactNode;
+    /** Shown when the manifest carries no metadata at all. */
+    emptyMessage?: React.ReactNode;
+    /** Hides the metadata entries that are already shown as priority fields. */
+    hideDuplicateFields?: boolean;
+    className?: string;
+    headingClassName?: string;
+    tableClassName?: string;
+    labelClassName?: string;
+    valueClassName?: string;
+};
+/** The manifest's descriptive metadata as a definition table. */
+declare const IIIFMetadataPanel: React.FC<IIIFMetadataPanelProps>;
+
+type IIIFModelsPanelProps = {
+    heading?: React.ReactNode;
+    emptyMessage?: React.ReactNode;
+    visibilityLabel?: string;
+    transparencyLabel?: string;
+    className?: string;
+    headingClassName?: string;
+    listClassName?: string;
+    itemClassName?: string;
+};
+/** Per-model visibility and transparency toggles, one row per model annotation. */
+declare const IIIFModelsPanel: React.FC<IIIFModelsPanelProps>;
+
+type IIIFMultiManifestModelsPanelProps = {
+    heading?: React.ReactNode;
+    emptyMessage?: React.ReactNode;
+    visibilityLabel?: string;
+    transparencyLabel?: string;
+    className?: string;
+    headingClassName?: string;
+    groupClassName?: string;
+    groupHeadingClassName?: string;
+    listClassName?: string;
+    itemClassName?: string;
+};
+/** Per-model visibility and transparency toggles, grouped under a heading per source manifest. */
+declare const IIIFMultiManifestModelsPanel: React.FC<IIIFMultiManifestModelsPanelProps>;
+
+type IIIFSavedViewsPanelProps = {
+    heading?: React.ReactNode;
+    emptyMessage?: React.ReactNode;
+    /** Hides the "save current view" control, leaving only the manifest's own cameras. */
+    hideSaveControl?: boolean;
+    saveLabel?: string;
+    /**
+     * Called with the IIIF camera annotation for the current view. When omitted, the annotation is
+     * shown in the panel so it can be copied into a manifest.
+     */
+    onSaveView?: (annotation: Record<string, unknown>) => void;
+    className?: string;
+    headingClassName?: string;
+    listClassName?: string;
+    buttonClassName?: string;
+};
+/** Buttons for the manifest's camera annotations, plus a way to capture the current view. */
+declare const IIIFSavedViewsPanel: React.FC<IIIFSavedViewsPanelProps>;
+
+/** Endonyms for the languages this collection publishes in; anything else falls back to the tag. */
+declare const LANGUAGE_NAMES: Record<string, string>;
+type IIIFLanguageSwitcherProps = {
+    label?: React.ReactNode;
+    /** Merged over {@link LANGUAGE_NAMES} to name additional languages. */
+    languageNames?: Record<string, string>;
+    /** Renders the switcher even when the manifest offers only one language. */
+    alwaysShow?: boolean;
+    className?: string;
+    labelClassName?: string;
+    selectClassName?: string;
+};
+/**
+ * Switches the language used for labels and metadata.
+ *
+ * Hidden when the manifest has one language or fewer, since there is nothing to choose between.
+ */
+declare const IIIFLanguageSwitcher: React.FC<IIIFLanguageSwitcherProps>;
+
+/**
+ * Ranking used when an annotation offers the same model in several formats. Nexus wins because it
+ * is the only one 3DHOP streams progressively; glTF ranks last because 3DHOP cannot load it at all
+ * and it is only ever a fallback worth reporting.
+ */
+declare const FORMAT_PREFERENCE: Record<string, number>;
+/** Picks the source this viewer can make the best use of. See {@link FORMAT_PREFERENCE}. */
+declare function selectBestSource(source: IIIFModelSource | IIIFModelSource[] | undefined): IIIFModelSource | undefined;
+type ParseOptions = {
+    /** Language used to resolve labels and values. Defaults to `'en'`. */
+    language?: string;
+    onDiagnostic?: DiagnosticHandler;
+};
+/**
+ * Parses an already-fetched IIIF manifest into the viewer-ready shape.
+ *
+ * Unrecognised annotations are reported through `onDiagnostic` and skipped rather than aborting
+ * the parse, so a manifest with one bad entry still renders the rest.
+ */
+declare function parseManifest(manifest: IIIFManifest, options?: ParseOptions): ParsedManifest;
+type LoadManifestOptions = ParseOptions & {
+    signal?: AbortSignal;
+    /** Injectable for testing and for consumers with their own HTTP stack. */
+    fetchImpl?: typeof fetch;
+};
+/** Fetches a manifest by URL and parses it. Rejects on network, JSON, or HTTP-status failures. */
+declare function loadManifest(url: string, options?: LoadManifestOptions): Promise<ParsedManifest>;
+
+type ParseCollectionOptions = {
+    /** Language used to resolve labels and summaries. Defaults to `'en'`. */
+    language?: string;
+    onDiagnostic?: DiagnosticHandler;
+};
+/**
+ * Parses an already-fetched IIIF Collection into the listing a picker or carousel needs.
+ *
+ * Items are expected to be `Manifest` references; anything else (e.g. a nested `Collection`) is
+ * reported through `onDiagnostic` and skipped rather than aborting the parse.
+ */
+declare function parseCollection(collection: IIIFCollection, options?: ParseCollectionOptions): ParsedCollection;
+type LoadCollectionOptions = ParseCollectionOptions & {
+    signal?: AbortSignal;
+    /** Injectable for testing and for consumers with their own HTTP stack. */
+    fetchImpl?: typeof fetch;
+};
+/** Fetches a collection by URL and parses it. Rejects on network, JSON, or HTTP-status failures. */
+declare function loadCollection(url: string, options?: LoadCollectionOptions): Promise<ParsedCollection>;
+
+/**
+ * Length units the viewer understands, expressed as their size in metres.
+ *
+ * `um` and `µm` are both accepted because manifests are hand-authored and the micro sign is
+ * awkward to type.
+ */
+declare const UNITS_IN_METRES: Record<string, number>;
+type UnitName = keyof typeof UNITS_IN_METRES;
+declare function isKnownUnit(unit: string | undefined | null): boolean;
+/**
+ * Multiplier that converts a length in `fromUnit` to the same length in `toUnit`.
+ *
+ * Unknown units are treated as a factor of 1 rather than raising, matching the original viewer:
+ * a manifest with a typo'd unit still renders, just unscaled.
+ */
+declare function getUnitScaleFactor(fromUnit: string | undefined | null, toUnit: string | undefined | null): number;
+
+/**
+ * A minimal 4x4 matrix implementation matching SpiderGL's conventions, so the matrices produced
+ * here can be handed straight to 3DHOP.
+ *
+ * Layout is **column-major**: `m[column * 4 + row]`, the same order WebGL expects. A translation
+ * therefore lives in elements 12, 13 and 14. `multiply(a, b)` returns `a · b`, so the rightmost
+ * factor is applied to a point first.
+ *
+ * This is reimplemented rather than delegated to the `SglMat4` global so it can be unit-tested in
+ * Node and does not depend on 3DHOP's scripts having loaded.
+ */
+type Mat4 = number[];
+
+/**
+ * Converts a single IIIF transform to a matrix.
+ *
+ * `RotateTransform` has two authored forms: per-axis Euler angles (`{ x, y, z }`, degrees) and a
+ * single axis-angle (`{ axis: 'y', angle: 45 }`). The Euler form is composed Z, then Y, then X,
+ * matching how 3DHOP's presenter interprets its own `rotation` triple.
+ */
+declare function transformToMatrix(transform: IIIFTransform): Mat4;
+/**
+ * Composes an ordered IIIF transform list into a single matrix.
+ *
+ * IIIF applies the transforms in the order they are listed, so the first entry acts on the model
+ * first. In matrix terms that makes it the rightmost factor: `Tn · … · T2 · T1`.
+ *
+ * This is why the list must be composed rather than flattened into a single translation/rotation/
+ * scale triple: with a flattened triple, `translate` then `rotate` and `rotate` then `translate`
+ * produce the same result, when they should not.
+ */
+declare function composeTransforms(transforms: readonly IIIFTransform[] | undefined): Mat4;
+type ModelMatrixOptions = {
+    /** Placement of the model in scene coordinates, from the annotation's `PointSelector`. */
+    position?: Vector3;
+    /** The annotation's `transform` list, in authored order. */
+    transforms?: readonly IIIFTransform[];
+    /**
+     * Converts scene-level coordinates — the `PointSelector` and any `TranslateTransform` — from the
+     * manifest's measure unit to the display unit.
+     */
+    sceneScale?: number;
+    /**
+     * Converts the mesh's own vertex coordinates from the unit that model is authored in to the
+     * display unit. Differs from `sceneScale` only when the annotation overrides `measureUnit`.
+     */
+    geometryScale?: number;
+};
+/**
+ * Builds the full model matrix for one IIIF model annotation.
+ *
+ * ```text
+ * M = S(sceneScale) · T(position) · L · S(geometryScale / sceneScale)
+ * ```
+ *
+ * Read right to left, that is: bring the mesh's vertices from their own unit into the manifest's
+ * unit, apply the manifest's ordered transform list, place the result at the `PointSelector`
+ * position, then convert the whole scene from the manifest's unit to the display unit. Keeping the
+ * unit conversions on the outside and inside — rather than folding them into the instance scale —
+ * is what makes positions and translations scale correctly alongside the geometry.
+ *
+ * When the model does not override `measureUnit`, `geometryScale / sceneScale` is 1 and the
+ * innermost factor drops out.
+ */
+declare function buildModelMatrix({ position, transforms, sceneScale, geometryScale }: ModelMatrixOptions): Mat4;
+
+/**
+ * 3DHOP's turntable trackball state: `[phi, theta, panX, panY, panZ, distance]`.
+ *
+ * `phi` (heading) and `theta` (elevation) are degrees; the pan and distance components are in
+ * scene-radius units, i.e. already divided by the scene radius.
+ */
+type TrackballState = [number, number, number, number, number, number];
+/**
+ * The scene framing the presenter derives once a scene is loaded. Both values are needed to move
+ * between world coordinates and the normalised space the trackball operates in.
+ */
+type SceneFraming = {
+    sceneCenter: Vector3;
+    /** Reciprocal of the scene radius, as the presenter stores it. */
+    sceneRadiusInv: number;
+};
+/**
+ * Converts a world-space camera to a trackball state. The exact inverse of {@link track2view}.
+ *
+ * Heading is recovered from the view direction, falling back to the up vector only when the camera
+ * looks straight up or straight down and the direction has no horizontal component left to read.
+ * The fallback is deliberately narrow: a camera parsed out of a manifest has no authored up vector
+ * — {@link cameraToView} synthesises world up — so leaning on it for any merely steep view would
+ * lose the heading entirely.
+ *
+ * Both branches use `atan2` rather than `asin`. An `asin` only spans a half-turn and needs a
+ * quadrant correction, which is easy to get wrong below the horizon, and it divides by a cosine
+ * that vanishes exactly where the input is already ill-conditioned.
+ */
+declare function view2track(view: View, framing: SceneFraming): TrackballState;
+/** Inverse of {@link view2track}. */
+declare function track2view(trackState: TrackballState, framing: SceneFraming, fov?: number): View;
+/**
+ * Builds the world-space view a manifest camera describes.
+ *
+ * The look-at point is resolved in priority order: an explicit `lookAt` point, then the position of
+ * the model the camera's `lookAt` refers to, then the scene centre.
+ */
+declare function cameraToView(camera: ParsedCamera, framing: SceneFraming, models?: readonly ParsedModel[]): View;
+type CameraAnnotationOptions = {
+    /** Base for the generated `@id`s. */
+    idBase?: string;
+    label?: string;
+    /** Id of the `Scene` the camera annotation targets. */
+    sceneId?: string;
+};
+/**
+ * Serialises a view as an IIIF camera annotation, ready to be pasted into a manifest's
+ * `AnnotationPage`. The inverse of what {@link cameraToView} consumes.
+ */
+declare function viewToCameraAnnotation(view: View, { idBase, label, sceneId }?: CameraAnnotationOptions): Record<string, unknown>;
+
+/**
+ * Languages tried, in order, when the requested one is absent. Mirrors the behaviour of the
+ * original viewer, which was authored for a Norwegian institution publishing in English.
+ */
+declare const DEFAULT_FALLBACK_LANGUAGES: string[];
+/**
+ * Resolves an IIIF language map to a single string.
+ *
+ * Tries `language`, then each of `fallbacks`, then any remaining language in the map. Returns an
+ * empty string when nothing is available, so callers can render without null checks.
+ *
+ * Unlike the original implementation this takes the language as an argument rather than reading a
+ * module-level global, so two viewers on one page can show different languages.
+ */
+declare function resolveLanguageMap(value: LocalizableValue | undefined | null, language: string, fallbacks?: readonly string[]): string;
+/**
+ * Collects every language tag used by the language maps reachable from `value`.
+ *
+ * IIIF uses the tag `none` for values that carry no language; it is a valid key but not a language
+ * a user would ever choose, so it is excluded.
+ */
+declare function collectLanguages(value: unknown, into?: Set<string>): Set<string>;
+
+export { type CameraAnnotationOptions, DEFAULT_FALLBACK_LANGUAGES, DEFAULT_MEASURE_UNIT, type Diagnostic, type DiagnosticHandler, FORMAT_PREFERENCE, type IIIFAnnotation, type IIIFAnnotationBody, type IIIFAnnotationPage, type IIIFAnnotationTarget, type IIIFCollection, IIIFCollectionCarousel, type IIIFCollectionCarouselProps, type IIIFCollectionContextValue, type IIIFCollectionItem, IIIFCollectionPicker, type IIIFCollectionPickerProps, IIIFCollectionProvider, type IIIFCollectionProviderProps, type IIIFCollectionStatus, type IIIFContextValue, IIIFLanguageSwitcher, type IIIFLanguageSwitcherProps, type IIIFManifest, type IIIFMetadataEntry, IIIFMetadataPanel, type IIIFMetadataPanelProps, type IIIFModelSource, IIIFModelsPanel, type IIIFModelsPanelProps, type IIIFMultiManifestContextValue, IIIFMultiManifestModelsPanel, type IIIFMultiManifestModelsPanelProps, IIIFMultiManifestProvider, type IIIFMultiManifestProviderProps, type IIIFMultiManifestStatus, IIIFMultiManifestViewer, type IIIFMultiManifestViewerProps, type IIIFPointSelector, IIIFProvider, type IIIFProviderProps, IIIFSavedViewsPanel, type IIIFSavedViewsPanelProps, type IIIFScene, type IIIFStatus, IIIFSummary, type IIIFSummaryProps, type IIIFThumbnail, type IIIFTransform, IIIFViewer, type IIIFViewerProps, LANGUAGE_NAMES, type LanguageMap, type LoadCollectionOptions, type LoadManifestOptions, type LocalizableValue, type ManifestGroup, type ManifestSceneEntry, type ModelMatrixOptions, type ParseCollectionOptions, type ParseOptions, type ParsedCamera, type ParsedCollection, type ParsedCollectionItem, type ParsedManifest, type ParsedMetadata, type ParsedModel, type SceneFraming, type SceneFromManifest, type SceneFromManifests, type ToModelsOptions, type ToMultiModelsOptions, type TrackballState, UNITS_IN_METRES, type UnitName, type Vector3, type View, buildModelMatrix, cameraToView, collectLanguages, composeTransforms, getUnitScaleFactor, isKnownUnit, layoutManifests, loadCollection, loadManifest, parseCollection, parseManifest, resolveLanguageMap, sceneFromManifest, sceneFromManifests, selectBestSource, track2view, transformToMatrix, useIIIFCollection, useIIIFManifest, useIIIFMultiManifest, view2track, viewToCameraAnnotation };