@semiont/react-ui 0.5.10 → 0.5.11

package/dist/index.d.ts

@@ -2,11 +2,11 @@ import * as _semiont_react_ui from '@semiont/react-ui';
 import { Annotation, ResourceId, Selector, components, ResourceDescriptor, ValidationResult, StateUnit, GatheredContext, EventMap, AnnotationId, AnchorStrategy, AnchorConfidence, StoredEventLike, ConnectionState, BackendDownload, ProgressEvent, AccessToken } from '@semiont/core';
 export { Annotation } from '@semiont/core';
 import * as React$1 from 'react';
-import React__default, { ComponentType, ReactNode, KeyboardEvent as KeyboardEvent$1, Component, ErrorInfo, Ref } from 'react';
+import React__default, { ComponentType, ReactNode, KeyboardEvent as KeyboardEvent$1, Component, ErrorInfo, MouseEvent, Ref } from 'react';
 import * as _codemirror_state from '@codemirror/state';
 import { HighlightStyle } from '@codemirror/language';
 import { WidgetType } from '@codemirror/view';
-import { SemiontBrowser, SessionStorage, SessionFactory, SemiontSession, OpenResource, TagSchema, UploadProgress, SemiontClient, BeckonStateUnit, MarkStateUnit, GatherStateUnit, YieldStateUnit, ReferencedByEntry } from '@semiont/sdk';
+import { SemiontClient, SemiontSession, SemiontBrowser, SessionStorage, SessionFactory, OpenResource, TagSchema, UploadProgress, BeckonStateUnit, MarkStateUnit, GatherStateUnit, YieldStateUnit, ReferencedByEntry } from '@semiont/sdk';
 export { BeckonStateUnit, GatherStateUnit, GenerateDocumentOptions, HOVER_DELAY_MS, HoverHandlers, MarkStateUnit, MatchStateUnit, PendingAnnotation, SearchPipeline, SearchPipelineOptions, SearchState, TagSchema, YieldStateUnit, createBeckonStateUnit, createGatherStateUnit, createHoverHandlers, createMarkStateUnit, createMatchStateUnit, createSearchPipeline, createYieldStateUnit } from '@semiont/sdk';
 import { Observable } from 'rxjs';
 
@@ -359,26 +359,38 @@ declare function hideWidgetPreview(container: HTMLElement): void;
 type SelectionMotivation = 'linking' | 'highlighting' | 'assessing' | 'commenting' | 'tagging';
 type ClickAction = 'detail' | 'follow' | 'jsonld' | 'deleting';
 type ShapeType = 'rectangle' | 'circle' | 'polygon';
+/** The bar's composable controls, in fixed render order. */
+type ToolbarPart = 'clickAction' | 'mode' | 'selection' | 'shape';
 interface AnnotateToolbarProps {
     selectedMotivation: SelectionMotivation | null;
     selectedClick: ClickAction;
-    showSelectionGroup?: boolean;
     showDeleteButton?: boolean;
-    showShapeGroup?: boolean;
     selectedShape?: ShapeType;
     mediaType?: string | null;
     annotateMode: boolean;
     annotators: Record<string, Annotator>;
+    /**
+     * Which controls to render (composition over CSS hiding). Default: all four.
+     * Order is fixed (click, mode, selection, shape); shape stays media-gated.
+     */
+    parts?: ToolbarPart[];
+    /**
+     * Purely presentational: each control reports the chosen value via its
+     * callback; the owner (viewer instance or host) applies it. The bar holds no
+     * pref state, emits no bus events, and touches no storage.
+     */
+    onModeChange?: (mode: boolean) => void;
+    onClickActionChange?: (action: ClickAction) => void;
+    onSelectionChange?: (motivation: SelectionMotivation | null) => void;
+    onShapeChange?: (shape: ShapeType) => void;
+    compact?: boolean;
 }
 /**
- * Toolbar for annotation controls with mode, selection, click, and shape options
- *
- * @emits mark:selection-changed - Selection motivation changed. Payload: { motivation: SelectionMotivation | null }
- * @emits mark:click-changed - Click action mode changed. Payload: { action: ClickAction }
- * @emits mark:shape-changed - Drawing shape changed. Payload: { shape: ShapeType }
- * @emits mark:mode-toggled - View mode toggled between browse and annotate. Payload: undefined
+ * Toolbar for annotation controls with mode, selection, click, and shape options.
+ * Purely presentational (TOOLBAR-PREFS-AS-PROPS): renders the given values for the
+ * given `parts` and reports choices via the on*Change callbacks — no bus, no storage.
  */
-declare function AnnotateToolbar({ selectedMotivation, selectedClick, showSelectionGroup, showDeleteButton, showShapeGroup, selectedShape, mediaType, annotateMode, annotators }: AnnotateToolbarProps): React__default.JSX.Element;
+declare function AnnotateToolbar({ selectedMotivation, selectedClick, showDeleteButton, selectedShape, mediaType, annotateMode, annotators, parts, onModeChange, onClickActionChange, onSelectionChange, onShapeChange, compact, }: AnnotateToolbarProps): React__default.JSX.Element;
 
 /**
  * Media Type Shape Support
@@ -392,10 +404,17 @@ declare function AnnotateToolbar({ selectedMotivation, selectedClick, showSelect
  */
 type SelectorType = 'fragment' | 'svg' | 'text';
 /**
- * Get supported annotation shapes for a given media type
+ * Get supported annotation shapes for a given media type.
  *
- * PDF: Only rectangles (FragmentSelector with RFC 3778 viewrect)
- * Images: All shapes (SvgSelector supports rect, circle, polygon)
+ * This set is the host-facing CONTRACT for "which shapes can this medium
+ * draw" — gate shape UI on it directly.
+ *
+ * PDF: only rectangles (FragmentSelector with RFC 3778 viewrect).
+ * Images: all shapes (SvgSelector supports rect, circle, polygon).
+ * Everything else — including text media and absent/unknown types — supports
+ * NONE: those anchor by character offsets (TextPositionSelector /
+ * TextQuoteSelector), and no selector can carry a shape. Mirrors
+ * `getSelectorType`'s 'text' fallback.
  *
  * @param mediaType - MIME type of the resource (e.g., 'application/pdf', 'image/png')
  * @returns Array of supported shape types for annotation
@@ -840,8 +859,16 @@ declare function useLocalStorage<T>(key: string, initialValue: T): [T, (value: T
 interface UseResourceContentResult {
     content: string;
     loading: boolean;
+    error: Error | null;
 }
-declare function useResourceContent(rUri: ResourceId, resource: ResourceDescriptor, enabled?: boolean): UseResourceContentResult;
+/**
+ * Fetch + decode a resource's primary representation from a bare client — the
+ * content sibling of `useResourceLoader`/`useMediaToken` (bring-your-own-client;
+ * `null` → idle). Headless: errors are RETURNED, never toasted — the host
+ * decides chrome (the Browser page toasts; an embedded host may render inline
+ * or ignore). `enabled=false` fetches nothing (the binary/media-token path).
+ */
+declare function useResourceContent(client: SemiontClient | null, rUri: ResourceId, resource: ResourceDescriptor, enabled?: boolean): UseResourceContentResult;
 
 interface ResourceGatherOptions {
     depth?: number;
@@ -865,6 +892,104 @@ interface UseResourceGatherResult {
  */
 declare function useResourceGather(): UseResourceGatherResult;
 
+interface UseResourceLoaderResult {
+    resource: ResourceDescriptor | undefined;
+    annotations: AnnotationsCollection;
+    loading: boolean;
+    error: Error | null;
+}
+/**
+ * Load a resource + its annotations from a bare client — no page, no composite
+ * state unit, no providers. The lightweight alternative to `ResourceViewerPage`
+ * for a bring-your-own-session host; feed the result straight into `<ResourceViewer>`.
+ *
+ * `loading` is true until BOTH the resource and its annotation list have first
+ * emitted; `annotations` is bucketed via the shared `groupAnnotations`. A null
+ * client subscribes to nothing (stays loading) and re-subscribes when one arrives.
+ */
+declare function useResourceLoader(client: SemiontClient | null, resourceId: ResourceId): UseResourceLoaderResult;
+
+interface UseMediaTokenResult {
+    token: string | undefined;
+    loading: boolean;
+}
+/**
+ * Mint (and periodically refresh) a short-lived authed media token for a
+ * resource — the query param that makes `<img>` / PDF URLs load. Takes the
+ * client explicitly (not `useSemiont()`), so a bring-your-own-session host can
+ * use it with a bare session; the batteries-included page passes `session.client`.
+ */
+declare function useMediaToken(client: SemiontClient | null, id: ResourceId): UseMediaTokenResult;
+
+/**
+ * Subscribe to session-scoped bus events on an explicit `SemiontSession` — the
+ * provider-free counterpart to `useEventSubscriptions`. The embeddable viewer
+ * path takes its session as a prop (bring-your-own-session), so it can't reach
+ * the app-scoped `SemiontBrowser` bus; every channel it needs (`mark:*`,
+ * `browse:click`) is session-scoped anyway and reaches it via `session.subscribe`.
+ *
+ * Same stable-handler / stable-key semantics as `useEventSubscriptions`:
+ * handlers may change every render without re-subscribing; re-subscription
+ * happens only when the set of channel names or the session changes. A null
+ * session subscribes to nothing, and cleanly re-subscribes when one arrives.
+ */
+declare function useSessionEventSubscriptions(session: SemiontSession | null, subscriptions: {
+    [K in keyof EventMap]?: (payload: EventMap[K]) => void;
+}): void;
+
+interface ToolbarPrefs {
+    annotateMode: boolean;
+    setAnnotateMode: (mode: boolean) => void;
+    clickAction: ClickAction;
+    setClickAction: (action: ClickAction) => void;
+    selectionMotivation: SelectionMotivation | null;
+    setSelectionMotivation: (motivation: SelectionMotivation | null) => void;
+    shape: ShapeType;
+    setShape: (shape: ShapeType) => void;
+}
+/**
+ * The POLICY layer for toolbar preferences (TOOLBAR-PREFS-AS-PROPS): one shared,
+ * localStorage-persisted prefs state — the Semiont Browser's global-toolbar UX,
+ * relocated from inside the components to a visible page-layer hook. Feed the
+ * returned values/setters to every viewer you compose (as its controlled props)
+ * and they stay in lockstep and survive remounts. The components themselves hold
+ * no persistence and no cross-instance sync; this hook is the one legitimate home
+ * for both. Keys are the historical ones, so existing users' prefs carry over.
+ *
+ * `selectorType` scopes the SHAPE pref exactly as before: per selector type
+ * (persisted only for 'svg'; 'fragment' is always rectangle).
+ */
+declare function useToolbarPrefs(selectorType?: SelectorType): ToolbarPrefs;
+
+/**
+ * A claimed `mark:requested` — the typed event payload (selector + motivation +
+ * source), re-exported rather than a parallel shape.
+ */
+type PendingCreation = EventMap['mark:requested'];
+/**
+ * The consuming half of the viewer's capture/policy split (HEADLESS-CREATION-SEAM).
+ *
+ * The viewer captures gestures and emits source-scoped `mark:requested`; this
+ * hook claims them for ONE viewer: an event is claimed iff
+ * `enabled && event.source === resourceId` — N mounted hooks on one session each
+ * claim only their own (the multi-mount contract MARK-REQUESTED-RESOURCE-SCOPE
+ * created). A new request for the same resource REPLACES an unresolved pending
+ * (the user reselected; the stale pending is abandoned).
+ *
+ * Headless by contract: no creation call, no UI, no toast in here — resolution
+ * (chooser flows, body forms, `mark.annotation`) is host policy. Session-first
+ * like every subscribing primitive (`session.subscribe` is the sanctioned
+ * generic-channel path); `null` → inert.
+ *
+ * @param session  Session whose bus carries this viewer's events; null → inert.
+ * @param resourceId  Claim only events whose `source` is this resource.
+ * @param enabled  The host's annotate-mode gate — browse-mode viewers never claim.
+ */
+declare function usePendingCreation(session: SemiontSession | null, resourceId: ResourceId, enabled: boolean): {
+    pending: PendingCreation | null;
+    clearPending: () => void;
+};
+
 interface SemiontProviderProps {
     /** Inject a fully-constructed browser (tests, embedded hosts that build their own). Omit to use the default. */
     browser?: SemiontBrowser;
@@ -1305,10 +1430,23 @@ interface ResourceTagsInlineProps {
     resourceId: string;
     tags: string[];
     isEditing: boolean;
+    /**
+     * Commit: called ONCE per edit with the FULL new tag set (the host diffs —
+     * its SDK call takes `(current, updated)`). Awaited; the editor renders
+     * inert while the returned promise is pending.
+     */
     onUpdate: (tags: string[]) => Promise<void>;
     disabled?: boolean;
+    /**
+     * The KB's registered entity types — the CONTROLLED VOCABULARY, host-supplied
+     * (the component is session-less; hosts fetch via `browse.entityTypes()`).
+     * Adds are a picker constrained to it: no free-text minting. Without it the
+     * editor is REMOVAL-ONLY (it cannot offer valid candidates). Removal is never
+     * vocabulary-gated — stale/unregistered tags must stay removable.
+     */
+    vocabulary?: string[];
 }
-declare function ResourceTagsInline({ tags }: ResourceTagsInlineProps): React$1.JSX.Element | null;
+declare function ResourceTagsInline({ tags, isEditing, onUpdate, disabled, vocabulary, }: ResourceTagsInlineProps): React$1.JSX.Element | null;
 
 type ToastType = 'success' | 'error' | 'info' | 'warning';
 interface ToastMessage {
@@ -1418,6 +1556,8 @@ declare function AnnotationOverlay({ annotations, imageWidth, imageHeight, displ
 type DrawingMode = 'rectangle' | 'polygon' | 'circle' | 'freeform' | null;
 interface SvgDrawingCanvasProps {
     imageUrl: string;
+    /** The '@id' of the annotated resource — stamped as `source` on mark:requested (multi-viewer routing). */
+    resourceUri: string;
     existingAnnotations?: Annotation[];
     drawingMode: DrawingMode;
     selectedMotivation?: SelectionMotivation | null;
@@ -1432,7 +1572,7 @@ interface SvgDrawingCanvasProps {
  * @emits browse:click - Annotation clicked on canvas. Payload: { annotationId: string, motivation: Motivation }
  * @emits mark:requested - New annotation drawn on canvas. Payload: { selector: SvgSelector, motivation: SelectionMotivation }
  */
-declare function SvgDrawingCanvas({ imageUrl, existingAnnotations, drawingMode, selectedMotivation, session, hoveredAnnotationId, selectedAnnotationId }: SvgDrawingCanvasProps): React__default.JSX.Element;
+declare function SvgDrawingCanvas({ imageUrl, resourceUri, existingAnnotations, drawingMode, selectedMotivation, session, hoveredAnnotationId, selectedAnnotationId }: SvgDrawingCanvasProps): React__default.JSX.Element;
 
 interface KeyboardShortcutsHelpModalProps {
     isOpen: boolean;
@@ -1467,7 +1607,8 @@ declare function SessionExpiredModal(): React$1.JSX.Element;
 interface Props$8 {
     content: string;
     mimeType?: string;
-    resourceUri?: string;
+    /** The '@id' of the shown resource — stamped as `source` on mark:requested (multi-viewer routing). */
+    resourceUri: string;
     annotations: AnnotationsCollection;
     uiState: AnnotationUIState;
     onUIStateChange?: (state: Partial<AnnotationUIState>) => void;
@@ -1478,17 +1619,22 @@ interface Props$8 {
     showLineNumbers?: boolean;
     hoverDelayMs?: number;
     annotateMode: boolean;
+    /** Session for the shown resource — its client emits mark:* / mark.request; its bus feeds toolbar + beckon events. */
+    session: SemiontSession | null;
+    /** Recently-created annotation ids to sparkle (host-provided; was ResourceAnnotationsContext). */
+    newAnnotationIds?: Set<string>;
+    /** The bar's Mode control reports the chosen mode here (the owner applies it). */
+    onModeChange?: (mode: boolean) => void;
+    /** Render the built-in bar (default). false → no bar; selection capture and drawing stay live. */
+    showToolbar?: boolean;
 }
 /**
  * View component for annotating resources with text selection and drawing
  *
  * @emits mark:requested - User requested to create annotation. Payload: { selector: Selector | Selector[], motivation: SelectionMotivation }
- * @subscribes mark:selection-changed - Toolbar selection changed. Payload: { motivation: string | null }
- * @subscribes mark:click-changed - Toolbar click action changed. Payload: { action: string }
- * @subscribes mark:shape-changed - Toolbar shape changed. Payload: { shape: string }
  * @subscribes beckon:hover - Annotation hovered. Payload: { annotationId: string | null }
  */
-declare function AnnotateView({ content, mimeType, resourceUri, annotations, uiState, onUIStateChange, enableWidgets, getTargetResourceName, generatingReferenceId, showLineNumbers, hoverDelayMs, annotateMode }: Props$8): React$1.JSX.Element;
+declare function AnnotateView({ content, mimeType, resourceUri, annotations, uiState, onUIStateChange, enableWidgets, getTargetResourceName, generatingReferenceId, showLineNumbers, hoverDelayMs, annotateMode, session, newAnnotationIds, onModeChange, showToolbar, }: Props$8): React$1.JSX.Element;
 
 interface Props$7 {
     rUri: ResourceId;
@@ -1500,6 +1646,29 @@ interface Props$7 {
 }
 declare function AnnotationHistory({ rUri, hoveredAnnotationId, onEventHover, onEventClick, Link, routes }: Props$7): React__default.JSX.Element | null;
 
+/**
+ * Common props for a read-only ("browse") media renderer. `content` is decoded
+ * text for the text renderer, or a media URL for the image / PDF renderers.
+ * A consumer can implement this interface to swap in a custom renderer.
+ */
+interface MediaRendererProps {
+    content: string;
+    mimeType: string;
+    resourceUri: string;
+    annotations: Annotation[];
+}
+/** Read-only media dispatch, keyed by the registry render mode. */
+type BrowseMediaRenderers = Partial<Record<string, ComponentType<MediaRendererProps>>>;
+declare function TextBrowseRenderer({ content }: MediaRendererProps): React$1.JSX.Element;
+declare function ImageBrowseRenderer({ content, mimeType }: MediaRendererProps): React$1.JSX.Element;
+declare function PdfBrowseRenderer({ content, resourceUri, annotations }: MediaRendererProps): React$1.JSX.Element;
+/**
+ * Default read-only media renderers. `BrowseView` merges a caller's `renderers`
+ * override on top of these, so a host can swap one renderer (e.g. its own PDF
+ * viewer) or add a mode without forking the view.
+ */
+declare const defaultBrowseRenderers: Record<'text' | 'image' | 'pdf', ComponentType<MediaRendererProps>>;
+
 interface Props$6 {
     content: string;
     mimeType: string;
@@ -1509,6 +1678,36 @@ interface Props$6 {
     selectedClick?: ClickAction;
     annotateMode: boolean;
     hoverDelayMs?: number;
+    /** Session for the shown resource — emits browse:click / beckon:hover; its bus feeds beckon events. */
+    session: SemiontSession | null;
+    /** Recently-created annotation ids to sparkle (host-provided; was ResourceAnnotationsContext). */
+    newAnnotationIds?: Set<string>;
+    /** Override the read-only media renderers (render mode → renderer); merged over the defaults. */
+    renderers?: BrowseMediaRenderers;
+    /** A content link (`<a href>` in the rendered content) was clicked. The viewer preventDefaults and
+     *  delegates; it never navigates on its own. Omit → the click is still blocked (nothing happens). */
+    onLinkClick?: (link: {
+        href: string;
+        event: MouseEvent;
+    }) => void;
+    /** A RESOLVED reference span is hovered: fires after the dwell AND the referent's cached descriptor
+     *  resolves; `null` on leave (only if a hover fired — stubs stay silent). Host renders its own preview. */
+    onReferenceHover?: (hover: ReferenceHover | null) => void;
+    /** Inline display variant: auto-height to content, no inner scroll container, no pane chrome —
+     *  drops into a chat bubble / card / list item. Default: fill-the-pane (unchanged). */
+    inline?: boolean;
+    /** The bar's Mode control reports the chosen mode here (the owner applies it). */
+    onModeChange?: (mode: boolean) => void;
+    /** The bar's Click control reports the chosen action here (the owner applies it). */
+    onClickActionChange?: (action: ClickAction) => void;
+    /** Render the built-in bar (default). false → no bar; all other seams stay live. */
+    showToolbar?: boolean;
+}
+/** Payload for `onReferenceHover` — the hovered linking annotation, its resolved referent, and where the span is. */
+interface ReferenceHover {
+    annotation: Annotation;
+    referent: ResourceDescriptor;
+    anchorRect: DOMRect;
 }
 /**
  * View component for browsing annotated resources in read-only mode.
@@ -1523,7 +1722,7 @@ interface Props$6 {
  * @subscribes beckon:hover - Highlight annotation on hover. Payload: { annotationId: string | null }
  * @subscribes beckon:focus - Scroll to and highlight annotation. Payload: { annotationId: string }
  */
-declare const BrowseView: React$1.MemoExoticComponent<({ content, mimeType, resourceUri, annotations, selectedClick, annotateMode, hoverDelayMs }: Props$6) => React$1.JSX.Element>;
+declare const BrowseView: React$1.MemoExoticComponent<({ content, mimeType, resourceUri, annotations, selectedClick, onModeChange, onClickActionChange, showToolbar, annotateMode, hoverDelayMs, session, newAnnotationIds, renderers, onLinkClick, onReferenceHover, inline, }: Props$6) => React$1.JSX.Element>;
 
 type TranslateFn$4 = (key: string, params?: Record<string, string | number>) => string;
 interface Props$5 {
@@ -1548,9 +1747,11 @@ declare function HistoryEvent({ event, annotations, allEvents, isRelated, t, Lin
  * - Automatically invalidates cache when annotations change
  * - No manual refetch needed - events handle cache invalidation
  *
- * Requirements:
- * - Must be wrapped in SemiontProvider (which owns the session's event bus)
- * - Must be wrapped in CacheContext (provides cache manager)
+ * Bring-your-own-session: the `session` (SemiontSession) and the host's
+ * navigation / panel callbacks come in as props — no SemiontProvider required.
+ * Every event it subscribes to is session-scoped (mark:*, browse:click) and
+ * reaches it via `session.subscribe`. Translations fall back to built-in English
+ * when no TranslationProvider is mounted; caching flows through `session.client.browse.*`.
  *
  * Event flow:
  *   make-meaning → EventLog → SSE → EventBus → ResourceViewer → Cache invalidation
@@ -1563,25 +1764,62 @@ interface Props$4 {
         content: string;
     };
     annotations: AnnotationsCollection;
+    /** Session for the shown resource — its client mutates/invalidates, its bus feeds annotation events. */
+    session: SemiontSession | null;
+    /** Host-owned navigation: a resolved reference was followed. Omit for a view with no follow behavior. */
+    onOpenResource?: (resourceId: string) => void;
+    /** Host-owned panel control (annotation clicks open a panel). Omit for hosts without side panels. */
+    onOpenPanel?: (event: EventMap['panel:open']) => void;
+    /** A content link in the rendered content was clicked — the viewer preventDefaults and delegates; it never navigates on its own. */
+    onLinkClick?: (link: {
+        href: string;
+        event: React__default.MouseEvent;
+    }) => void;
+    /** A resolved reference span is hovered (after dwell + referent descriptor resolve); `null` on leave. Host renders its own preview. */
+    onReferenceHover?: (hover: ReferenceHover | null) => void;
+    /** Inline display variant: auto-height, no inner scroll, no pane chrome (browse path). Default: fill-the-pane. */
+    inline?: boolean;
+    /** Recently-created annotation ids to sparkle (threaded to the browse/annotate subtree). */
+    newAnnotationIds?: Set<string>;
     generatingReferenceId?: string | null;
     showLineNumbers?: boolean;
     hoverDelayMs?: number;
     hoveredAnnotationId?: string | null;
+    /**
+     * Toolbar preferences as controlled props (TOOLBAR-PREFS-AS-PROPS). Supply a value
+     * to own that pref: the instance renders it and reports intents via the callback —
+     * it never self-mutates, never persists, never listens to other instances. Omit for
+     * a plain uncontrolled default (false / 'detail' / 'linking' / 'rectangle').
+     * Hosts wanting the shared+persisted Browser UX compose `useToolbarPrefs()`.
+     */
+    annotateMode?: boolean;
+    onAnnotateModeChange?: (mode: boolean) => void;
+    clickAction?: ClickAction;
+    onClickActionChange?: (action: ClickAction) => void;
+    selectionMotivation?: SelectionMotivation | null;
+    onSelectionMotivationChange?: (motivation: SelectionMotivation | null) => void;
+    shape?: ShapeType;
+    onShapeChange?: (shape: ShapeType) => void;
+    /**
+     * Render the built-in AnnotateToolbar (default true — today's behavior,
+     * byte-identical). `false` → no bar at any internal site (browse + every
+     * annotate render mode), while every seam stays live: annotate-mode selection
+     * capture, image/pdf drawing, `mark.request` emission, and the controlled
+     * props. Tier-2 hosts compose their own controls from the controlled props;
+     * this makes that opt-out a contract instead of a CSS override.
+     */
+    showToolbar?: boolean;
 }
 /**
  * @emits mark:delete - User requested to delete annotation. Payload: { annotationId: string }
  * @emits panel:open - Request to open panel with annotation. Payload: { panel: string, scrollToAnnotationId?: string, motivation?: Motivation }
  *
- * @subscribes mark:mode-toggled - Toggles between browse and annotate mode. Payload: { mode: 'browse' | 'annotate' }
  * @subscribes mark:added - New annotation was added. Payload: { annotation: Annotation }
  * @subscribes mark:removed - Annotation was removed. Payload: { annotationId: string }
  * @subscribes mark:body-updated - Annotation was updated. Payload: { annotation: Annotation }
- * @subscribes mark:selection-changed - Text selection tool changed. Payload: { selection: boolean }
- * @subscribes mark:click-changed - Click annotation tool changed. Payload: { click: 'detail' | 'scroll' | null }
- * @subscribes mark:shape-changed - Drawing shape changed. Payload: { shape: string }
  * @subscribes browse:click - User clicked on annotation. Payload: { annotationId: string }
  */
-declare function ResourceViewer({ resource, annotations, generatingReferenceId, showLineNumbers, hoverDelayMs, hoveredAnnotationId: hoveredAnnotationIdProp }: Props$4): React__default.JSX.Element;
+declare function ResourceViewer({ resource, annotations, session, onOpenResource, onOpenPanel, onLinkClick, onReferenceHover, inline, newAnnotationIds, generatingReferenceId, showLineNumbers, hoverDelayMs, hoveredAnnotationId: hoveredAnnotationIdProp, annotateMode: annotateModeProp, onAnnotateModeChange, clickAction: clickActionProp, onClickActionChange, selectionMotivation: selectionMotivationProp, onSelectionMotivationChange, shape: shapeProp, onShapeChange, showToolbar, }: Props$4): React__default.JSX.Element;
 
 interface AssessmentEntryProps {
     assessment: Annotation;
@@ -1598,6 +1836,8 @@ interface PendingAnnotation$5 {
     motivation: Motivation$5;
 }
 interface AssessmentPanelProps {
+    /** The '@id' of the panel's resource — stamped as `source` on mark:submit (multi-viewer routing). */
+    resourceId: string;
     annotations: Annotation[];
     pendingAnnotation: PendingAnnotation$5 | null;
     isAssisting?: boolean;
@@ -1617,7 +1857,7 @@ interface AssessmentPanelProps {
  * @emits mark:cancel-pending - Cancel pending assessment annotation. Payload: undefined
  * @subscribes browse:click - Annotation clicked. Payload: { annotationId: string }
  */
-declare function AssessmentPanel({ annotations, pendingAnnotation, isAssisting, progress, locale, sourceLanguage, annotateMode, scrollToAnnotationId, onScrollCompleted, hoveredAnnotationId, }: AssessmentPanelProps): React$1.JSX.Element;
+declare function AssessmentPanel({ resourceId, annotations, pendingAnnotation, isAssisting, progress, locale, sourceLanguage, annotateMode, scrollToAnnotationId, onScrollCompleted, hoveredAnnotationId, }: AssessmentPanelProps): React$1.JSX.Element;
 
 interface Props$3 {
     /**
@@ -1660,6 +1900,8 @@ interface PendingAnnotation$4 {
     motivation: Motivation$4;
 }
 interface CommentsPanelProps {
+    /** The '@id' of the panel's resource — stamped as `source` on mark:submit (multi-viewer routing). */
+    resourceId: string;
     annotations: Annotation[];
     pendingAnnotation: PendingAnnotation$4 | null;
     annotateMode?: boolean;
@@ -1679,7 +1921,7 @@ interface CommentsPanelProps {
  * @emits mark:cancel-pending - Cancel pending comment annotation. Payload: undefined
  * @subscribes browse:click - Annotation clicked. Payload: { annotationId: string }
  */
-declare function CommentsPanel({ annotations, pendingAnnotation, annotateMode, isAssisting, progress, locale, sourceLanguage, scrollToAnnotationId, onScrollCompleted, hoveredAnnotationId, }: CommentsPanelProps): React$1.JSX.Element;
+declare function CommentsPanel({ resourceId, annotations, pendingAnnotation, annotateMode, isAssisting, progress, locale, sourceLanguage, scrollToAnnotationId, onScrollCompleted, hoveredAnnotationId, }: CommentsPanelProps): React$1.JSX.Element;
 
 type JobProgress$4 = components['schemas']['JobProgress'];
 interface AssistSectionProps {
@@ -1720,6 +1962,8 @@ interface PendingAnnotation$3 {
     motivation: Motivation$3;
 }
 interface HighlightPanelProps {
+    /** The '@id' of the panel's resource — stamped as `source` on mark:submit (multi-viewer routing). */
+    resourceId: string;
     annotations: Annotation[];
     pendingAnnotation: PendingAnnotation$3 | null;
     isAssisting?: boolean;
@@ -1737,7 +1981,7 @@ interface HighlightPanelProps {
  * @emits mark:create - Create new highlight annotation (auto-triggered). Payload: { motivation: 'highlighting', selector: Selector | Selector[], body: Body[] }
  * @subscribes browse:click - Annotation clicked. Payload: { annotationId: string }
  */
-declare function HighlightPanel({ annotations, pendingAnnotation, isAssisting, progress, annotateMode, scrollToAnnotationId, onScrollCompleted, hoveredAnnotationId, sourceLanguage, }: HighlightPanelProps): React$1.JSX.Element;
+declare function HighlightPanel({ resourceId, annotations, pendingAnnotation, isAssisting, progress, annotateMode, scrollToAnnotationId, onScrollCompleted, hoveredAnnotationId, sourceLanguage, }: HighlightPanelProps): React$1.JSX.Element;
 
 interface Props$2 {
     resourceId: ResourceId;
@@ -1784,6 +2028,8 @@ interface PendingAnnotation$2 {
     motivation: Motivation$2;
 }
 interface Props$1 {
+    /** The '@id' of the panel's resource — stamped as `source` on mark:submit (multi-viewer routing). */
+    resourceId: string;
     annotations?: Annotation[];
     isAssisting: boolean;
     progress: JobProgress$2 | null;
@@ -1811,7 +2057,7 @@ interface Props$1 {
  * @emits mark:cancel-pending - Cancel pending reference annotation. Payload: undefined
  * @subscribes browse:click - Annotation clicked. Payload: { annotationId: string }
  */
-declare function ReferencesPanel({ annotations, isAssisting, progress, annotateMode, Link, routes, allEntityTypes, generatingReferenceId, referencedBy, referencedByLoading, pendingAnnotation, scrollToAnnotationId, onScrollCompleted, hoveredAnnotationId, locale, sourceLanguage, }: Props$1): React__default.JSX.Element;
+declare function ReferencesPanel({ resourceId, annotations, isAssisting, progress, annotateMode, Link, routes, allEntityTypes, generatingReferenceId, referencedBy, referencedByLoading, pendingAnnotation, scrollToAnnotationId, onScrollCompleted, hoveredAnnotationId, locale, sourceLanguage, }: Props$1): React__default.JSX.Element;
 
 type Agent = components['schemas']['Agent'];
 interface Props {
@@ -1867,6 +2113,8 @@ interface PendingAnnotation$1 {
     motivation: Motivation$1;
 }
 interface TaggingPanelProps {
+    /** The '@id' of the panel's resource — stamped as `source` on mark:submit (multi-viewer routing). */
+    resourceId: string;
     annotations: Annotation[];
     annotateMode?: boolean;
     isAssisting?: boolean;
@@ -1888,7 +2136,7 @@ interface TaggingPanelProps {
  * @emits mark:create - Create new tag annotation. Payload: { motivation: 'tagging', selector: Selector | Selector[], body: Body[] }
  * @subscribes browse:click - Annotation clicked. Payload: { annotationId: string }
  */
-declare function TaggingPanel({ annotations, annotateMode, isAssisting, progress, pendingAnnotation, scrollToAnnotationId, onScrollCompleted, hoveredAnnotationId, locale, sourceLanguage, }: TaggingPanelProps): React$1.JSX.Element;
+declare function TaggingPanel({ resourceId, annotations, annotateMode, isAssisting, progress, pendingAnnotation, scrollToAnnotationId, onScrollCompleted, hoveredAnnotationId, locale, sourceLanguage, }: TaggingPanelProps): React$1.JSX.Element;
 
 type JobProgress = components['schemas']['JobProgress'];
 
@@ -1918,7 +2166,7 @@ interface UnifiedAnnotationsPanelProps {
     generatingReferenceId?: string | null;
     referencedBy?: any[];
     referencedByLoading?: boolean;
-    resourceId?: string;
+    resourceId: string;
     initialTab?: TabKey;
     initialTabGeneration?: number;
     scrollToAnnotationId?: string | null;
@@ -3840,5 +4088,5 @@ declare function useShellStateUnit(): ShellStateUnit;
  */
 declare function useObservable<T>(obs$: Observable<T> | null | undefined): T | undefined;
 
-export { ANNOTATORS, AVAILABLE_LOCALES, AdminDevOpsPage, AdminExchangePage, AdminSecurityPage, AdminUsersPage, AnnotateReferencesProgressWidget, AnnotateToolbar, AnnotateView, AnnotationHistory, AnnotationOverlay, AnnotationProvider, AssessmentEntry, AssessmentPanel, AssistSection, AsyncErrorBoundary, AuthErrorDisplay, BrowseView, Button, ButtonGroup, COMMON_PANELS, CodeMirrorRenderer, CollaborationPanel, CollapsibleResourceNavigation, CommentEntry, CommentsPanel, ComposeLoadingState, EntityTagsPage, EntityTypeBadges, ErrorBoundary, ExportCard, Footer, HighlightEntry, HighlightPanel, HistoryEvent, ImageURLSchema, ImageViewer, ImportCard, ImportProgress, JsonLdPanel, JsonLdView, KeyboardShortcutsHelpModal, LeftSidebar, LinkedDataPage, LiveRegionProvider, NavigationMenu, OAuthUserSchema, ObservableLink, PageLayout, PanelHeader, PermissionDeniedModal, PopupContainer, PopupHeader, ProtectedErrorBoundary, RESOURCE_PANELS, RecentDocumentsPage, ReferenceEntry, ReferenceResolutionWidget, ReferenceWizardModal, ReferencesPanel, ResizeHandle, ResourceAnnotationsProvider, ResourceCard, ResourceComposePage, ResourceDiscoveryPage, ResourceErrorState, ResourceGenerateModal, ResourceInfoPanel, ResourceLoadingState, ResourceSearchModal, ResourceTagsInline, ResourceViewer, ResourceViewerPage, SearchModal, SelectedTextDisplay, SemiontBranding, SemiontFavicon, SemiontProvider, SessionExpiredModal, SessionExpiryBanner, SessionTimer, SettingsPanel, SignInForm, SignUpForm, SimpleNavigation, SkipLinks, SortableResourceTab, StatisticsPanel, StatusDisplay, SvgDrawingCanvas, TagEntry, TagSchemasPage, TaggingPanel, ThemeProvider, ToastContainer, ToastProvider, Toolbar, TranslationProvider, UnifiedAnnotationsPanel, UnifiedHeader, UploadProgressBar, UserMenuSkeleton, WebBrowserStorage, WelcomePage, applyHighlights, buildSourceToRenderedMap, buildTextNodeIndex, buttonStyles, clearHighlights, createAdminSecurityStateUnit, createAdminUsersStateUnit, createComposePageStateUnit, createDiscoverStateUnit, createEntityTagsStateUnit, createExchangeStateUnit, createResourceLoaderStateUnit, createResourceViewerPageStateUnit, createSessionStateUnit, createShellStateUnit, createWelcomeStateUnit, cssVariables, faviconPaths, formatTime, generateCSSVariables, getResourceIcon, getSelectedShapeForSelectorType, getSelectorType, getShortcutDisplay, getSupportedShapes, hideWidgetPreview, isShapeSupported, jsonLightHighlightStyle, jsonLightTheme, resolveAnnotationRanges, sanitizeImageURL, saveSelectedShapeForSelectorType, setPdfWorkerSrc, showWidgetPreview, supportsDetection, toOverlayAnnotations, tokens, useAnnotationManager, useDebounce, useDebouncedCallback, useDocumentAnnouncements, useDoubleKeyPress, useDropdown, useEventSubscription, useEventSubscriptions, useFormAnnouncements, useHoverDelay, useHoverEmitter, useIsTyping, useKeyboardShortcuts, useLanguageChangeAnnouncements, useLineNumbers, useLiveRegion, useLoadingState, useLocalStorage, useObservable, useObservableExternalNavigation, useObservableRouter, usePanelWidth, usePreloadTranslations, useResourceAnnotations, useResourceContent, useResourceGather, useResourceLoadingAnnouncements, useRovingTabIndex, useSearchAnnouncements, useSemiont, useSessionExpiry, useShellStateUnit, useStateUnit, useTheme, useToast, useTranslations };
-export type { AdminDevOpsPageProps, AdminExchangePageProps, AdminExchangePageTranslations, AdminSecurityPageProps, AdminSecurityStateUnit, AdminUser, AdminUserStats, AdminUsersPageProps, AdminUsersStateUnit, AnnotationConfig, AnnotationCreationHandler, AnnotationGroups, AnnotationHandlers, AnnotationManager, AnnotationProviderProps, AnnotationUIState, AnnotationsCollection, Annotator, AuthErrorDisplayProps, AvailableLocale, BorderRadiusToken, ButtonGroupProps, ButtonProps, ClickAction, CloneData, CollapsibleResourceNavigationProps, ColorToken, ComposeLoadingStateProps, ComposeMode, ComposePageStateUnit, ComposeParams, CreateAnnotationParams, CreateConfig, DeleteAnnotationParams, DetectionConfig, DevOpsFeature, DiscoverStateUnit, DrawingMode, EntityTagsPageProps, EntityTagsStateUnit, ExchangeStateUnit, ExportCardProps, ExportCardTranslations, HoverEmitterProps, ImportCardProps, ImportCardTranslations, ImportPreview, ImportProgressProps, ImportProgressTranslations, JobProgressWidgetTranslations, KeyboardShortcut, LinkComponentProps, LinkedDataPageProps, LinkedDataPageTranslations, Motivation$8 as Motivation, NavigationItem, NavigationMenuHelper, NavigationProps, OAuthProvider, OAuthUser, ObservableLinkProps, OverlayAnnotation, RecentDocumentsPageProps, ReferenceData, ReferenceWizardModalProps, ResolvedTheme, ResourceCardProps, ResourceComposePageProps, ResourceDiscoveryPageProps, ResourceErrorStateProps, ResourceGatherOptions, ResourceGenerateModalProps, ResourceGenerateModalTranslations, ResourceLoaderStateUnit, ResourceSearchModalProps, ResourceViewerPageProps, ResourceViewerPageStateUnit, RouteBuilder, SaveResourceParams$1 as SaveResourceParams, SearchModalProps, SelectionMotivation, SelectorType, SemiontProviderProps, SemiontResource$1 as SemiontResource, SessionStateUnit, ShadowToken, ShapeType, ShellStateUnit, ShellStateUnitOptions, SignInFormProps, SignUpFormProps, SimpleNavigationItem, SimpleNavigationProps, SortableResourceTabProps, SpacingToken, TagSchemasPageProps, TextSegment, TextSelection, Theme, ToastMessage, ToastType, ToolbarPanelType, TransitionToken, TranslationManager, TranslationProviderProps, TypographyToken, UICreateAnnotationParams, UploadProgressBarProps, UseResourceContentResult, UseResourceGatherResult, WelcomePageProps, WelcomeStateUnit, WizardState };
+export { ANNOTATORS, AVAILABLE_LOCALES, AdminDevOpsPage, AdminExchangePage, AdminSecurityPage, AdminUsersPage, AnnotateReferencesProgressWidget, AnnotateToolbar, AnnotateView, AnnotationHistory, AnnotationOverlay, AnnotationProvider, AssessmentEntry, AssessmentPanel, AssistSection, AsyncErrorBoundary, AuthErrorDisplay, BrowseView, Button, ButtonGroup, COMMON_PANELS, CodeMirrorRenderer, CollaborationPanel, CollapsibleResourceNavigation, CommentEntry, CommentsPanel, ComposeLoadingState, EntityTagsPage, EntityTypeBadges, ErrorBoundary, ExportCard, Footer, HighlightEntry, HighlightPanel, HistoryEvent, ImageBrowseRenderer, ImageURLSchema, ImageViewer, ImportCard, ImportProgress, JsonLdPanel, JsonLdView, KeyboardShortcutsHelpModal, LeftSidebar, LinkedDataPage, LiveRegionProvider, NavigationMenu, OAuthUserSchema, ObservableLink, PageLayout, PanelHeader, PdfBrowseRenderer, PermissionDeniedModal, PopupContainer, PopupHeader, ProtectedErrorBoundary, RESOURCE_PANELS, RecentDocumentsPage, ReferenceEntry, ReferenceResolutionWidget, ReferenceWizardModal, ReferencesPanel, ResizeHandle, ResourceAnnotationsProvider, ResourceCard, ResourceComposePage, ResourceDiscoveryPage, ResourceErrorState, ResourceGenerateModal, ResourceInfoPanel, ResourceLoadingState, ResourceSearchModal, ResourceTagsInline, ResourceViewer, ResourceViewerPage, SearchModal, SelectedTextDisplay, SemiontBranding, SemiontFavicon, SemiontProvider, SessionExpiredModal, SessionExpiryBanner, SessionTimer, SettingsPanel, SignInForm, SignUpForm, SimpleNavigation, SkipLinks, SortableResourceTab, StatisticsPanel, StatusDisplay, SvgDrawingCanvas, TagEntry, TagSchemasPage, TaggingPanel, TextBrowseRenderer, ThemeProvider, ToastContainer, ToastProvider, Toolbar, TranslationProvider, UnifiedAnnotationsPanel, UnifiedHeader, UploadProgressBar, UserMenuSkeleton, WebBrowserStorage, WelcomePage, applyHighlights, buildSourceToRenderedMap, buildTextNodeIndex, buttonStyles, clearHighlights, createAdminSecurityStateUnit, createAdminUsersStateUnit, createComposePageStateUnit, createDiscoverStateUnit, createEntityTagsStateUnit, createExchangeStateUnit, createResourceLoaderStateUnit, createResourceViewerPageStateUnit, createSessionStateUnit, createShellStateUnit, createWelcomeStateUnit, cssVariables, defaultBrowseRenderers, faviconPaths, formatTime, generateCSSVariables, getResourceIcon, getSelectedShapeForSelectorType, getSelectorType, getShortcutDisplay, getSupportedShapes, hideWidgetPreview, isShapeSupported, jsonLightHighlightStyle, jsonLightTheme, resolveAnnotationRanges, sanitizeImageURL, saveSelectedShapeForSelectorType, setPdfWorkerSrc, showWidgetPreview, supportsDetection, toOverlayAnnotations, tokens, useAnnotationManager, useDebounce, useDebouncedCallback, useDocumentAnnouncements, useDoubleKeyPress, useDropdown, useEventSubscription, useEventSubscriptions, useFormAnnouncements, useHoverDelay, useHoverEmitter, useIsTyping, useKeyboardShortcuts, useLanguageChangeAnnouncements, useLineNumbers, useLiveRegion, useLoadingState, useLocalStorage, useMediaToken, useObservable, useObservableExternalNavigation, useObservableRouter, usePanelWidth, usePendingCreation, usePreloadTranslations, useResourceAnnotations, useResourceContent, useResourceGather, useResourceLoader, useResourceLoadingAnnouncements, useRovingTabIndex, useSearchAnnouncements, useSemiont, useSessionEventSubscriptions, useSessionExpiry, useShellStateUnit, useStateUnit, useTheme, useToast, useToolbarPrefs, useTranslations };
+export type { AdminDevOpsPageProps, AdminExchangePageProps, AdminExchangePageTranslations, AdminSecurityPageProps, AdminSecurityStateUnit, AdminUser, AdminUserStats, AdminUsersPageProps, AdminUsersStateUnit, AnnotationConfig, AnnotationCreationHandler, AnnotationGroups, AnnotationHandlers, AnnotationManager, AnnotationProviderProps, AnnotationUIState, AnnotationsCollection, Annotator, AuthErrorDisplayProps, AvailableLocale, BorderRadiusToken, BrowseMediaRenderers, ButtonGroupProps, ButtonProps, ClickAction, CloneData, CollapsibleResourceNavigationProps, ColorToken, ComposeLoadingStateProps, ComposeMode, ComposePageStateUnit, ComposeParams, CreateAnnotationParams, CreateConfig, DeleteAnnotationParams, DetectionConfig, DevOpsFeature, DiscoverStateUnit, DrawingMode, EntityTagsPageProps, EntityTagsStateUnit, ExchangeStateUnit, ExportCardProps, ExportCardTranslations, HoverEmitterProps, ImportCardProps, ImportCardTranslations, ImportPreview, ImportProgressProps, ImportProgressTranslations, JobProgressWidgetTranslations, KeyboardShortcut, LinkComponentProps, LinkedDataPageProps, LinkedDataPageTranslations, MediaRendererProps, Motivation$8 as Motivation, NavigationItem, NavigationMenuHelper, NavigationProps, OAuthProvider, OAuthUser, ObservableLinkProps, OverlayAnnotation, PendingCreation, RecentDocumentsPageProps, ReferenceData, ReferenceHover, ReferenceWizardModalProps, ResolvedTheme, ResourceCardProps, ResourceComposePageProps, ResourceDiscoveryPageProps, ResourceErrorStateProps, ResourceGatherOptions, ResourceGenerateModalProps, ResourceGenerateModalTranslations, ResourceLoaderStateUnit, ResourceSearchModalProps, ResourceViewerPageProps, ResourceViewerPageStateUnit, RouteBuilder, SaveResourceParams$1 as SaveResourceParams, SearchModalProps, SelectionMotivation, SelectorType, SemiontProviderProps, SemiontResource$1 as SemiontResource, SessionStateUnit, ShadowToken, ShapeType, ShellStateUnit, ShellStateUnitOptions, SignInFormProps, SignUpFormProps, SimpleNavigationItem, SimpleNavigationProps, SortableResourceTabProps, SpacingToken, TagSchemasPageProps, TextSegment, TextSelection, Theme, ToastMessage, ToastType, ToolbarPanelType, ToolbarPart, ToolbarPrefs, TransitionToken, TranslationManager, TranslationProviderProps, TypographyToken, UICreateAnnotationParams, UploadProgressBarProps, UseMediaTokenResult, UseResourceContentResult, UseResourceGatherResult, UseResourceLoaderResult, WelcomePageProps, WelcomeStateUnit, WizardState };