@semiont/core 0.4.21 → 0.5.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Subject, OperatorFunction } from 'rxjs';
+import { Subject, OperatorFunction, Observable } from 'rxjs';
 import { E as EnvironmentConfig, P as PlatformType$1 } from './config.types-oPv3Ajk-.js';
 export { A as AnthropicProviderConfig, a as AppConfig, B as BackendServiceConfig, D as DatabaseServiceConfig, b as EmbeddingServiceConfig, F as FrontendServiceConfig, G as GraphDatabaseType, c as GraphServiceConfig, I as InferenceProvidersConfig, M as McpServiceConfig, O as OllamaProviderConfig, S as SemiontConfig, d as ServicePlatformConfig, e as ServicesConfig, f as SiteConfig, V as VectorsServiceConfig } from './config.types-oPv3Ajk-.js';
 
@@ -200,7 +200,7 @@ interface paths {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["GoogleAuthRequest"];
+                        "application/json": components["schemas"]["TokenRefreshResponse"];
                     };
                 };
                 /** @description Invalid or expired refresh token */
@@ -1664,52 +1664,7 @@ interface paths {
         delete?: never;
         options?: never;
         head?: never;
-        /**
-         * Update resource metadata
-         * @description Archive/unarchive or update entity types. Emits mark:archive / mark:unarchive / mark:update-entity-types on the bus; returns 202 immediately. Frontend reconciles state via SSE domain events.
-         */
-        patch: {
-            parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    id: string;
-                };
-                cookie?: never;
-            };
-            requestBody: {
-                content: {
-                    "application/json": components["schemas"]["UpdateResourceRequest"];
-                };
-            };
-            responses: {
-                /** @description Update accepted */
-                202: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content?: never;
-                };
-                /** @description Authentication required */
-                401: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": components["schemas"]["ErrorResponse"];
-                    };
-                };
-                /** @description Resource not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": components["schemas"]["ErrorResponse"];
-                    };
-                };
-            };
-        };
+        patch?: never;
         trace?: never;
     };
     "/api/resources/{id}": {
@@ -2040,14 +1995,6 @@ interface components {
             oldItem: components["schemas"]["TextualBody"] | components["schemas"]["SpecificResource"];
             newItem: components["schemas"]["TextualBody"] | components["schemas"]["SpecificResource"];
         };
-        BeckonResponse: {
-            /** @description Username or agent identifier that was beckoned */
-            participant: string;
-            /** @description Resource the attention was directed at */
-            resourceId: string;
-            /** @description Annotation the attention was directed at (if provided) */
-            annotationId?: string;
-        };
         CloneResourceWithTokenResponse: {
             /** @description Generated clone token */
             token: string;
@@ -2690,10 +2637,6 @@ interface components {
             /** @description Array of body modification operations to apply */
             operations: (components["schemas"]["BodyOperationAdd"] | components["schemas"]["BodyOperationRemove"] | components["schemas"]["BodyOperationReplace"])[];
         };
-        UpdateResourceRequest: {
-            entityTypes?: string[];
-            archived?: boolean;
-        };
         UpdateUserRequest: {
             isAdmin?: boolean;
             isActive?: boolean;
@@ -2764,14 +2707,14 @@ interface components {
         };
         /** @description Command payload sent on the bind:update-body bus channel to modify annotation bodies. */
         BindUpdateBodyCommand: {
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
             /** @description Client-supplied id used to match this command to its result event(s) on the events-stream. Generated by the route handler if absent. */
             correlationId: string;
             /** @description Branded AnnotationId of the annotation whose body is being updated */
             annotationId: string;
             /** @description Branded ResourceId of the resource the annotation belongs to */
             resourceId: string;
-            /** @description Branded UserId of the user performing the update */
-            userId?: string;
             /** @description List of body mutation operations to apply */
             operations: {
                 /**
@@ -3126,8 +3069,9 @@ interface components {
         };
         /** @description Command to mark a job as complete */
         JobCompleteCommand: {
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
             resourceId: string;
-            userId: string;
             jobId: string;
             jobType: components["schemas"]["JobType"];
             /** @description Annotation this job is attached to, when applicable. Lets the UI route completion feedback (toast, resolve state) to a specific annotation. */
@@ -3136,8 +3080,9 @@ interface components {
         };
         /** @description Command to mark a job as failed */
         JobFailCommand: {
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
             resourceId: string;
-            userId: string;
             jobId: string;
             jobType: components["schemas"]["JobType"];
             /** @description Annotation this job is attached to, when applicable. Lets the UI route failure feedback (error toast, revert state) to a specific annotation. */
@@ -3198,6 +3143,8 @@ interface components {
             jobId: string;
             jobType: string;
             resourceId: string;
+            /** @description DID of the user who initiated the job (audit). */
+            userId: string;
         };
         /** @description Result of a completed reference-annotation job. */
         JobReferenceAnnotationResult: {
@@ -3210,8 +3157,9 @@ interface components {
         };
         /** @description Command to report progress on a job */
         JobReportProgressCommand: {
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
             resourceId: string;
-            userId: string;
             jobId: string;
             jobType: components["schemas"]["JobType"];
             /** @description Annotation this job is attached to, when applicable. Lets the UI attach progress visuals to a specific annotation (e.g. a reference whose generation is running). */
@@ -3223,8 +3171,9 @@ interface components {
         JobResult: components["schemas"]["JobGenerationResult"] | components["schemas"]["JobReferenceAnnotationResult"] | components["schemas"]["JobHighlightAnnotationResult"] | components["schemas"]["JobAssessmentAnnotationResult"] | components["schemas"]["JobCommentAnnotationResult"] | components["schemas"]["JobTagAnnotationResult"];
         /** @description Command to start a job */
         JobStartCommand: {
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
             resourceId: string;
-            userId: string;
             jobId: string;
             jobType: components["schemas"]["JobType"];
             /** @description Annotation this job is attached to, when applicable. Set for annotation-scoped jobs like generation (from a specific reference). Unset for resource-scoped jobs like bulk reference/tag/highlight detection. */
@@ -3252,11 +3201,13 @@ interface components {
         /** @description Bus command to add a new entity type tag. */
         MarkAddEntityTypeCommand: {
             tag: string;
-            userId: string;
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
         };
         /** @description Bus command to archive a resource and optionally remove its file. */
         MarkArchiveCommand: {
-            userId?: string;
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
             resourceId: string;
             storageUri?: string;
             keepFile?: boolean;
@@ -3285,10 +3236,11 @@ interface components {
         };
         /** @description Bus command to create an annotation on a resource. */
         MarkCreateCommand: {
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
             /** @description Optional correlation id threaded from the originating mark:create-request. Propagated into event metadata by Stower so annotation-assembly can emit mark:create-ok after persistence completes. */
             correlationId?: string;
             annotation: components["schemas"]["Annotation"];
-            userId: string;
             resourceId: string;
         };
         /** @description Success response after creating an annotation. */
@@ -3303,8 +3255,9 @@ interface components {
         };
         /** @description Bus command to delete an annotation. */
         MarkDeleteCommand: {
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
             annotationId: string;
-            userId?: string;
             resourceId?: string;
         };
         /** @description Success response after deleting an annotation. */
@@ -3335,23 +3288,26 @@ interface components {
         };
         /** @description Bus command to unarchive a previously archived resource. */
         MarkUnarchiveCommand: {
-            userId?: string;
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
             resourceId: string;
             storageUri?: string;
         };
         /** @description Bus command to update an annotation's body with patch operations. */
         MarkUpdateBodyCommand: {
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
             /** @description Correlation id threaded from the originating route through to event metadata. Lets the events-stream deliver matched results to the client that initiated the bind. */
             correlationId?: string;
             annotationId: string;
-            userId: string;
             resourceId: string;
             operations: (components["schemas"]["BodyOperationAdd"] | components["schemas"]["BodyOperationRemove"] | components["schemas"]["BodyOperationReplace"])[];
         };
         /** @description Bus command to replace the entity types on a resource. */
         MarkUpdateEntityTypesCommand: {
             resourceId: string;
-            userId: string;
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
             currentEntityTypes: string[];
             updatedEntityTypes: string[];
         };
@@ -3425,12 +3381,13 @@ interface components {
         };
         /** @description Bus command to create a yielded resource in the knowledge base. */
         YieldCreateCommand: {
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
             name: string;
             storageUri: string;
             contentChecksum: string;
             byteSize: number;
             format: components["schemas"]["ContentFormat"];
-            userId: string;
             language?: string;
             entityTypes?: string[];
             creationMethod?: string;
@@ -3454,9 +3411,10 @@ interface components {
         };
         /** @description Bus command to move (rename) a yielded resource. */
         YieldMvCommand: {
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
             fromUri: string;
             toUri: string;
-            userId: string;
             noGit?: boolean;
         };
         /** @description Bus command to request yield (generation) of a new resource from an annotation. */
@@ -3477,11 +3435,12 @@ interface components {
         };
         /** @description Bus command to update a yielded resource's storage content. */
         YieldUpdateCommand: {
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
             resourceId: string;
             storageUri: string;
             contentChecksum: string;
             byteSize: number;
-            userId: string;
             noGit?: boolean;
         };
         /** @description Success response after updating a yielded resource. */
@@ -3611,18 +3570,57 @@ declare function resourceId(id: string): ResourceId;
 declare function annotationId(id: string): AnnotationId;
 declare function userId(id: string): UserId;
 
+/**
+ * Annotation types
+ */
+
+type RawAnnotation = components['schemas']['Annotation'];
+/**
+ * Domain-level Annotation type. Same shape as the OpenAPI-generated
+ * `components['schemas']['Annotation']`, but with a branded `AnnotationId`
+ * for the `id` field. Use this import everywhere the codebase refers to
+ * "an annotation"; the raw OpenAPI type is only used inside
+ * `@semiont/api-client` at the HTTP boundary.
+ *
+ * Implemented by intersection (not `Omit`) to be robust against generator
+ * drift — if the OpenAPI schema gets `additionalProperties: true` added,
+ * `Omit` on the resulting intersection type silently drops named fields.
+ */
+type Annotation = RawAnnotation & {
+    id: AnnotationId;
+};
+type AnnotationCategory = 'highlight' | 'reference';
+interface CreateAnnotationInternal {
+    id: AnnotationId;
+    motivation: Annotation['motivation'];
+    target: Annotation['target'];
+    body?: Annotation['body'];
+    creator: components['schemas']['Agent'];
+}
+
 /**
  * Graph types - Models for graph connections and relationships
  */
 
-type ResourceDescriptor = components['schemas']['ResourceDescriptor'];
-type Annotation$4 = components['schemas']['Annotation'];
+type RawResourceDescriptor = components['schemas']['ResourceDescriptor'];
+/**
+ * Domain-level ResourceDescriptor type. Same shape as the OpenAPI-generated
+ * `components['schemas']['ResourceDescriptor']`, but with a branded `ResourceId`
+ * for the `@id` field.
+ *
+ * Implemented by intersection (not `Omit`) because the generated raw type
+ * ends in `& { [key: string]: unknown }` — `Omit` on an intersection with
+ * an index signature drops almost all named fields.
+ */
+type ResourceDescriptor = RawResourceDescriptor & {
+    '@id': ResourceId;
+};
 /**
  * Represents a connection between resources through annotations
  */
 interface GraphConnection {
     targetResource: ResourceDescriptor;
-    annotations: Annotation$4[];
+    annotations: Annotation[];
     relationshipType?: string;
     bidirectional: boolean;
 }
@@ -3631,7 +3629,7 @@ interface GraphConnection {
  */
 interface GraphPath {
     resources: ResourceDescriptor[];
-    annotations: Annotation$4[];
+    annotations: Annotation[];
 }
 /**
  * Statistics about entity types in the graph
@@ -3649,6 +3647,15 @@ interface EntityTypeStats {
  * The PersistedEvent union derives from this catalog.
  */
 
+type AnnotationAddedPayload = components['schemas']['AnnotationAddedPayload'] & {
+    annotation: Annotation;
+};
+type AnnotationRemovedPayload = components['schemas']['AnnotationRemovedPayload'] & {
+    annotationId: AnnotationId;
+};
+type AnnotationBodyUpdatedPayload = components['schemas']['AnnotationBodyUpdatedPayload'] & {
+    annotationId: AnnotationId;
+};
 /**
  * Maps each persisted event type string to its OpenAPI payload schema.
  * Single source of truth for "what events get written to the log."
@@ -3660,9 +3667,9 @@ type PersistedEventCatalog = {
     'yield:moved': components['schemas']['ResourceMovedPayload'];
     'yield:representation-added': components['schemas']['RepresentationAddedPayload'];
     'yield:representation-removed': components['schemas']['RepresentationRemovedPayload'];
-    'mark:added': components['schemas']['AnnotationAddedPayload'];
-    'mark:removed': components['schemas']['AnnotationRemovedPayload'];
-    'mark:body-updated': components['schemas']['AnnotationBodyUpdatedPayload'];
+    'mark:added': AnnotationAddedPayload;
+    'mark:removed': AnnotationRemovedPayload;
+    'mark:body-updated': AnnotationBodyUpdatedPayload;
     'mark:archived': components['schemas']['ResourceArchivedPayload'];
     'mark:unarchived': components['schemas']['ResourceUnarchivedPayload'];
     'mark:entity-tag-added': components['schemas']['EntityTagChangedPayload'];
@@ -3754,7 +3761,7 @@ type StoredEvent<T extends EventBase = PersistedEvent> = T & {
 };
 type BodyItem = components['schemas']['TextualBody'] | components['schemas']['SpecificResource'];
 type BodyOperation = components['schemas']['BodyOperationAdd'] | components['schemas']['BodyOperationRemove'] | components['schemas']['BodyOperationReplace'];
-type Annotation$3 = components['schemas']['Annotation'];
+
 interface EventQuery {
     resourceId?: ResourceId;
     userId?: string;
@@ -3766,7 +3773,7 @@ interface EventQuery {
 }
 interface ResourceAnnotations {
     resourceId: ResourceId;
-    annotations: Annotation$3[];
+    annotations: Annotation[];
     version: number;
     updatedAt: string;
 }
@@ -3778,17 +3785,34 @@ interface ResourceAnnotations {
  * its payload type is defined here — domain events, commands, reads,
  * results, SSE stream payloads, and frontend UI events.
  *
- * Command and result payloads use OpenAPI-generated types (plain strings
- * for identifiers). Branded type safety (ResourceId, UserId, etc.) is
- * enforced at function boundaries, not on bus payloads — callers use
- * factory functions (resourceId(), userId()) at the consume boundary.
- *
- * Domain events (StoredEvent<Interface>) retain branded types as they
- * are the system of record, not wire-format payloads.
+ * Identifier discipline: where a payload carries an annotation or
+ * resource id, the TypeScript layer narrows the OpenAPI `string` to the
+ * branded type (`AnnotationId`, `ResourceId`, `UserId`). The runtime
+ * wire shape is unchanged (brands have no runtime representation);
+ * what this buys us is that command handlers don't have to re-brand
+ * at every seam. Brand once at the entry boundary (HTTP route handler,
+ * DOM attribute read, URL param parse), not at every bus hop in
+ * between. See `.plans/BRAND-UPSTREAM.md` for the rationale.
  *
  * Organized by flow (verb), then by category within each flow.
  */
 
+type MarkDeleteCommand = components['schemas']['MarkDeleteCommand'] & {
+    annotationId: AnnotationId;
+    resourceId?: ResourceId;
+};
+type MarkUpdateBodyCommand = components['schemas']['MarkUpdateBodyCommand'] & {
+    annotationId: AnnotationId;
+    resourceId: ResourceId;
+};
+type BindInitiateCommand = components['schemas']['BindInitiateCommand'] & {
+    annotationId: AnnotationId;
+    resourceId: ResourceId;
+};
+type BindUpdateBodyCommand = components['schemas']['BindUpdateBodyCommand'] & {
+    annotationId: AnnotationId;
+    resourceId: ResourceId;
+};
 /**
  * The unified EventMap — every channel on the EventBus.
  *
@@ -3848,8 +3872,8 @@ type EventMap = {
     'mark:unarchived': StoredEvent<EventOfType<'mark:unarchived'>>;
     'mark:create-request': components['schemas']['MarkCreateRequest'];
     'mark:create': components['schemas']['MarkCreateCommand'];
-    'mark:delete': components['schemas']['MarkDeleteCommand'];
-    'mark:update-body': components['schemas']['MarkUpdateBodyCommand'];
+    'mark:delete': MarkDeleteCommand;
+    'mark:update-body': MarkUpdateBodyCommand;
     'mark:archive': components['schemas']['MarkArchiveCommand'];
     'mark:unarchive': components['schemas']['MarkUnarchiveCommand'];
     'mark:update-entity-types': components['schemas']['MarkUpdateEntityTypesCommand'];
@@ -3874,8 +3898,8 @@ type EventMap = {
     'mark:selection-changed': components['schemas']['MarkSelectionChangedEvent'];
     'mark:click-changed': components['schemas']['MarkClickChangedEvent'];
     'mark:shape-changed': components['schemas']['MarkShapeChangedEvent'];
-    'bind:initiate': components['schemas']['BindInitiateCommand'];
-    'bind:update-body': components['schemas']['BindUpdateBodyCommand'];
+    'bind:initiate': BindInitiateCommand;
+    'bind:update-body': BindUpdateBodyCommand;
     'bind:body-updated': components['schemas']['BindBodyUpdated'];
     'bind:body-update-failed': components['schemas']['CommandError'];
     'match:search-requested': components['schemas']['MatchSearchRequest'];
@@ -4612,6 +4636,31 @@ interface Logger {
  */
 declare function errField(error: unknown): unknown;
 
+/**
+ * Bus logging — runtime-toggleable cross-wire visibility.
+ *
+ * One line per event that crosses a process boundary, in a grep-able
+ * format that's symmetric across frontend and backend:
+ *
+ *   [bus EMIT] <channel> [scope=X] [cid=<first8>] <payload>
+ *   [bus RECV] <channel> [scope=X] [cid=<first8>] <payload>
+ *   [bus SSE]  <channel> [scope=X] [cid=<first8>] <payload>
+ *
+ * Tier 1 of `.plans/OBSERVABILITY.md`. Forward-compatible with Tier 2:
+ * the `cid` printed here is exactly the prefix of the W3C trace-id we
+ * adopt later.
+ *
+ * Cost when disabled: one property read per call, zero allocations.
+ *
+ * Enable:
+ *   - Browser:  `window.__SEMIONT_BUS_LOG__ = true` (DevTools or e2e init)
+ *   - Node:     `SEMIONT_BUS_LOG=1` in the process env (read at module load)
+ */
+type BusOp = 'EMIT' | 'RECV' | 'SSE' | 'PUT' | 'GET';
+declare function busLogEnabled(): boolean;
+declare function setBusLogTraceIdProvider(fn: (() => string | undefined) | undefined): void;
+declare function busLog(op: BusOp, channel: string, payload: unknown, scope?: string): void;
+
 /**
  * Annotation body utilities
  *
@@ -4620,7 +4669,6 @@ declare function errField(error: unknown): unknown;
  * replace operations against an annotation body.
  */
 
-type Annotation$2 = components['schemas']['Annotation'];
 type BodyPurpose = components['schemas']['BodyPurpose'];
 /**
  * Identity of a body item for matching purposes.
@@ -4652,7 +4700,7 @@ type BodyItemIdentity = {
  *
  * See `BodyItemIdentity` for matching semantics.
  */
-declare function findBodyItem(body: Annotation$2['body'], identity: BodyItemIdentity): number;
+declare function findBodyItem(body: Annotation['body'], identity: BodyItemIdentity): number;
 
 /**
  * Annotation Assembly
@@ -4661,30 +4709,29 @@ declare function findBodyItem(body: Annotation$2['body'], identity: BodyItemIden
  * No EventBus, no persistence — just data transformation.
  */
 
-type Agent$1 = components['schemas']['Agent'];
-type Annotation$1 = components['schemas']['Annotation'];
+type Agent$2 = components['schemas']['Agent'];
 type AnnotationBody = components['schemas']['AnnotationBody'];
 type CreateAnnotationRequest = components['schemas']['CreateAnnotationRequest'];
 type UpdateAnnotationBodyRequest = components['schemas']['UpdateAnnotationBodyRequest'];
-type TextPositionSelector = components['schemas']['TextPositionSelector'];
-type SvgSelector = components['schemas']['SvgSelector'];
-type FragmentSelector = components['schemas']['FragmentSelector'];
+type TextPositionSelector$1 = components['schemas']['TextPositionSelector'];
+type SvgSelector$1 = components['schemas']['SvgSelector'];
+type FragmentSelector$1 = components['schemas']['FragmentSelector'];
 interface AssembledAnnotation {
-    annotation: Annotation$1;
+    annotation: Annotation;
     bodyArray: AnnotationBody[];
 }
 /**
  * Get TextPositionSelector from a selector (single or array)
  */
-declare function getTextPositionSelector(selector: Selector | Selector[] | undefined): TextPositionSelector | null;
+declare function getTextPositionSelector(selector: Selector | Selector[] | undefined): TextPositionSelector$1 | null;
 /**
  * Get SvgSelector from a selector (single or array)
  */
-declare function getSvgSelector(selector: Selector | Selector[] | undefined): SvgSelector | null;
+declare function getSvgSelector(selector: Selector | Selector[] | undefined): SvgSelector$1 | null;
 /**
  * Get FragmentSelector from a selector (single or array)
  */
-declare function getFragmentSelector(selector: Selector | Selector[] | undefined): FragmentSelector | null;
+declare function getFragmentSelector(selector: Selector | Selector[] | undefined): FragmentSelector$1 | null;
 /**
  * Validate SVG markup for W3C compliance
  *
@@ -4699,12 +4746,833 @@ declare function validateSvgMarkup(svg: string): string | null;
  *
  * Throws on invalid input (missing selector, missing motivation, invalid SVG).
  */
-declare function assembleAnnotation(request: CreateAnnotationRequest, creator: Agent$1): AssembledAnnotation;
+declare function assembleAnnotation(request: CreateAnnotationRequest, creator: Agent$2): AssembledAnnotation;
 /**
  * Apply body operations (add/remove/replace) to an annotation's body array.
  * Returns a new array — does not mutate the input.
  */
-declare function applyBodyOperations(body: Annotation$1['body'], operations: UpdateAnnotationBodyRequest['operations']): AnnotationBody[];
+declare function applyBodyOperations(body: Annotation['body'], operations: UpdateAnnotationBodyRequest['operations']): AnnotationBody[];
+
+/**
+ * Annotation and Selector Utilities
+ *
+ * Pure TypeScript utilities for working with W3C Web Annotations.
+ * No React dependencies - safe to use in any JavaScript environment.
+ *
+ * Body is either empty array (stub) or single SpecificResource (resolved)
+ * Body can be array of TextualBody (tagging) + SpecificResource (linking)
+ * Target can be simple string IRI or object with source and optional selector
+ */
+
+type HighlightAnnotation = Annotation;
+type ReferenceAnnotation = Annotation;
+type TextPositionSelector = components['schemas']['TextPositionSelector'];
+type TextQuoteSelector = components['schemas']['TextQuoteSelector'];
+type SvgSelector = components['schemas']['SvgSelector'];
+type FragmentSelector = components['schemas']['FragmentSelector'];
+
+/**
+ * Get the source from an annotation body (null if stub)
+ * Search for SpecificResource in body array
+ */
+declare function getBodySource(body: Annotation['body']): string | null;
+/**
+ * Get the type from an annotation body (returns first body type in array)
+ */
+declare function getBodyType(body: Annotation['body']): 'TextualBody' | 'SpecificResource' | null;
+/**
+ * Check if body is resolved (has a source)
+ * Check for SpecificResource in body array
+ */
+declare function isBodyResolved(body: Annotation['body']): boolean;
+/**
+ * Get the source IRI from target (handles both string and object forms)
+ */
+declare function getTargetSource(target: Annotation['target']): string;
+/**
+ * Get the selector from target (undefined if string or no selector)
+ */
+declare function getTargetSelector(target: Annotation['target']): {
+    type: "TextPositionSelector";
+    start: number;
+    end: number;
+} | {
+    type: "TextQuoteSelector";
+    exact: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: "SvgSelector";
+    value: string;
+} | {
+    type: "FragmentSelector";
+    value: string;
+    conformsTo?: string;
+} | ({
+    type: "TextPositionSelector";
+    start: number;
+    end: number;
+} | {
+    type: "TextQuoteSelector";
+    exact: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: "SvgSelector";
+    value: string;
+} | {
+    type: "FragmentSelector";
+    value: string;
+    conformsTo?: string;
+})[] | undefined;
+/**
+ * Check if target has a selector
+ */
+declare function hasTargetSelector(target: Annotation['target']): boolean;
+/**
+ * Type guard to check if an annotation is a highlight
+ */
+declare function isHighlight(annotation: Annotation): annotation is HighlightAnnotation;
+/**
+ * Type guard to check if an annotation is a reference (linking)
+ */
+declare function isReference(annotation: Annotation): annotation is ReferenceAnnotation;
+/**
+ * Type guard to check if an annotation is an assessment
+ */
+declare function isAssessment(annotation: Annotation): annotation is Annotation;
+/**
+ * Type guard to check if an annotation is a comment
+ */
+declare function isComment(annotation: Annotation): annotation is Annotation;
+/**
+ * Type guard to check if an annotation is a tag
+ */
+declare function isTag(annotation: Annotation): annotation is Annotation;
+/**
+ * Extract comment text from a comment annotation's body
+ * @param annotation - The annotation to extract comment text from
+ * @returns The comment text, or undefined if not a comment or no text found
+ */
+declare function getCommentText(annotation: Annotation): string | undefined;
+/**
+ * Type guard to check if a reference annotation is a stub (unresolved)
+ * Stub if no SpecificResource in body array
+ */
+declare function isStubReference(annotation: Annotation): boolean;
+/**
+ * Type guard to check if a reference annotation is resolved
+ * Resolved if SpecificResource exists in body array
+ */
+declare function isResolvedReference(annotation: Annotation): annotation is ReferenceAnnotation;
+/**
+ * Get the exact text from a selector (single or array)
+ *
+ * When selector is an array, tries to find a TextQuoteSelector (which has exact text).
+ * TextPositionSelector does not have exact text, only character offsets.
+ * Handles undefined selector (when target is a string IRI with no selector)
+ */
+declare function getExactText(selector: Selector | Selector[] | undefined): string;
+/**
+ * Get the exact text from an annotation's target selector
+ * Uses getTargetSelector helper to safely get selector
+ */
+declare function getAnnotationExactText(annotation: Annotation): string;
+/**
+ * Get the primary selector from a selector (single or array)
+ *
+ * When selector is an array, returns the first selector.
+ * When selector is a single object, returns it as-is.
+ */
+declare function getPrimarySelector(selector: Selector | Selector[]): Selector;
+/**
+ * Get TextQuoteSelector from a selector (single or array)
+ *
+ * Returns the first TextQuoteSelector found, or null if none exists.
+ */
+declare function getTextQuoteSelector(selector: Selector | Selector[]): TextQuoteSelector | null;
+/**
+ * Extract bounding box from SVG markup
+ *
+ * Attempts to extract x, y, width, height from the SVG viewBox or root element.
+ * Returns null if bounding box cannot be determined.
+ */
+declare function extractBoundingBox(svg: string): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | null;
+
+/**
+ * Helper functions for working with W3C ResourceDescriptor
+ */
+
+type Representation = components['schemas']['Representation'];
+/**
+ * Get the resource ID from @id property
+ *
+ * @id is always a bare ID (UUID), never a full URI.
+ */
+declare function getResourceId(resource: ResourceDescriptor | undefined): string | undefined;
+/**
+ * Get the primary representation (first or only representation)
+ */
+declare function getPrimaryRepresentation(resource: ResourceDescriptor | undefined): Representation | undefined;
+/**
+ * Get the media type from the primary representation
+ */
+declare function getPrimaryMediaType(resource: ResourceDescriptor | undefined): string | undefined;
+/**
+ * Get the checksum from the primary representation
+ */
+declare function getChecksum(resource: ResourceDescriptor | undefined): string | undefined;
+/**
+ * Get the language from the primary representation
+ */
+declare function getLanguage(resource: ResourceDescriptor | undefined): string | undefined;
+/**
+ * Get storage URI from primary representation
+ *
+ * @param resource - ResourceDescriptor
+ * @returns Storage URI or undefined
+ */
+declare function getStorageUri(resource: ResourceDescriptor | undefined): string | undefined;
+/**
+ * Get creator agent from wasAttributedTo
+ * Handles both single agent and array of agents
+ *
+ * @param resource - ResourceDescriptor
+ * @returns First agent or undefined
+ */
+declare function getCreator(resource: ResourceDescriptor | undefined): components['schemas']['Agent'] | undefined;
+/**
+ * Get derived-from URI
+ * Handles both single URI and array of URIs
+ *
+ * @param resource - ResourceDescriptor
+ * @returns First derivation URI or undefined
+ */
+declare function getDerivedFrom(resource: ResourceDescriptor | undefined): string | undefined;
+/**
+ * Check if resource is archived (application-specific field)
+ *
+ * @param resource - ResourceDescriptor
+ * @returns True if archived, false otherwise
+ */
+declare function isArchived(resource: ResourceDescriptor | undefined): boolean;
+/**
+ * Get entity types from resource (application-specific field)
+ *
+ * @param resource - ResourceDescriptor
+ * @returns Array of entity types, empty if not set
+ */
+declare function getResourceEntityTypes(resource: ResourceDescriptor | undefined): string[];
+/**
+ * Check if resource is a draft (application-specific field)
+ *
+ * @param resource - ResourceDescriptor
+ * @returns True if draft, false otherwise
+ */
+declare function isDraft(resource: ResourceDescriptor | undefined): boolean;
+/**
+ * Map charset names to Node.js Buffer encoding names
+ * Node.js Buffer.toString() supports: 'utf8', 'utf16le', 'latin1', 'base64', 'hex', 'ascii', 'binary', 'ucs2'
+ *
+ * @param charset - Charset name (e.g., "UTF-8", "ISO-8859-1", "Windows-1252")
+ * @returns Node.js BufferEncoding
+ */
+declare function getNodeEncoding(charset: string): BufferEncoding;
+/**
+ * Decode a representation buffer to string using the correct charset
+ * Extracts charset from media type and uses appropriate encoding
+ *
+ * @param buffer - The raw representation data
+ * @param mediaType - Media type with optional charset (e.g., "text/plain; charset=iso-8859-1")
+ * @returns Decoded string
+ *
+ * @example
+ * ```typescript
+ * const content = decodeRepresentation(buffer, "text/plain; charset=utf-8");
+ * const legacy = decodeRepresentation(buffer, "text/plain; charset=windows-1252");
+ * ```
+ */
+declare function decodeRepresentation(buffer: Buffer, mediaType: string): string;
+
+/**
+ * Transport interfaces — the shared contract for any wire-or-local
+ * communication path consumed by `SemiontClient`. Concrete implementations
+ * live alongside the runtime they wrap (`HttpTransport` in
+ * `@semiont/api-client`, in-process variants in `@semiont/make-meaning`,
+ * etc.).
+ *
+ * Two interfaces:
+ *
+ *   ITransport          — full surface: bus primitives + auth + admin +
+ *                         exchange + health/status + connection state.
+ *   IContentTransport   — binary I/O (putBinary / getBinary). Narrow by
+ *                         design because binary has different backpressure
+ *                         and streaming characteristics.
+ *
+ * The behavioral guarantees every implementation must honor are documented
+ * in `packages/core/docs/TRANSPORT-CONTRACT.md`.
+ */
+
+type Agent$1 = components['schemas']['Agent'];
+/**
+ * Six-state lifecycle for a transport's connection. Drives UI affordances
+ * (connecting spinners, reconnecting banners, etc.) and is observed via
+ * `ITransport.state$`.
+ *
+ *   initial      ─ pre-`start()`; never enters subscribers' streams
+ *                  except as the first replayed value
+ *   connecting   ─ in-flight initial open
+ *   open         ─ healthy, delivering events
+ *   reconnecting ─ open → dropped, retrying; may be transient
+ *   degraded     ─ has been reconnecting for > DEGRADED_THRESHOLD_MS;
+ *                  UI banner threshold; distinguishes brief mount-
+ *                  churn cycles from sustained disconnection
+ *   closed       ─ stop()/dispose() called; terminal
+ */
+type ConnectionState = 'initial' | 'connecting' | 'open' | 'reconnecting' | 'degraded' | 'closed';
+type AuthResponse = components['schemas']['AuthResponse'];
+type TokenRefreshResponse = components['schemas']['TokenRefreshResponse'];
+type AdminUserStatsResponse = components['schemas']['AdminUserStatsResponse'];
+type OAuthConfigResponse = components['schemas']['OAuthConfigResponse'];
+type ResponseContent<T> = T extends {
+    responses: {
+        200: {
+            content: {
+                'application/json': infer R;
+            };
+        };
+    };
+} ? R : T extends {
+    responses: {
+        201: {
+            content: {
+                'application/json': infer R;
+            };
+        };
+    };
+} ? R : T extends {
+    responses: {
+        202: {
+            content: {
+                'application/json': infer R;
+            };
+        };
+    };
+} ? R : never;
+type RequestContent<T> = T extends {
+    requestBody?: {
+        content: {
+            'application/json': infer R;
+        };
+    };
+} ? R : never;
+type HealthCheckResponse = ResponseContent<paths['/api/health']['get']>;
+type StatusResponse = ResponseContent<paths['/api/status']['get']>;
+type UserResponse = ResponseContent<paths['/api/users/me']['get']>;
+type UpdateUserRequest = RequestContent<paths['/api/admin/users/{id}']['patch']>;
+type UpdateUserResponse = ResponseContent<paths['/api/admin/users/{id}']['patch']>;
+type ListUsersResponse = ResponseContent<paths['/api/admin/users']['get']>;
+type ProgressEvent = {
+    phase: string;
+    message?: string;
+    result?: Record<string, unknown>;
+};
+type ProgressCallback = (event: ProgressEvent) => void;
+interface ITransport {
+    /**
+     * Base URL the transport speaks to. For HTTP this is `https://host[:port]`;
+     * for in-process transports, an opaque identifier (e.g. `local://kb-id`).
+     */
+    readonly baseUrl: BaseUrl;
+    /**
+     * Publish a payload on the named channel.
+     *
+     * `resourceScope`, when set, marks the emit as a resource-scoped
+     * broadcast — only delivered to subscribers attached to that
+     * resource's scope.
+     */
+    emit<K extends keyof EventMap>(channel: K, payload: EventMap[K], resourceScope?: ResourceId): Promise<void>;
+    on<K extends keyof EventMap>(channel: K, handler: (payload: EventMap[K]) => void): () => void;
+    stream<K extends keyof EventMap>(channel: K): Observable<EventMap[K]>;
+    /**
+     * Subscribe to a resource-scoped channel set. HTTP attaches a scope to
+     * its SSE connection; in-process transports may be a no-op because
+     * local events are delivered without scoping.
+     *
+     * Returns a disposer that detaches the scope when the last subscriber
+     * unsubscribes (ref-counted).
+     */
+    subscribeToResource(resourceId: ResourceId): () => void;
+    /**
+     * Hand the given bus to the transport so the transport can publish
+     * the events it receives into it. The reference flows
+     * client → transport (the client owns the bus); transports never
+     * construct or replace it. Concrete transports decide what "receives"
+     * means: HTTP bridges every channel it observes on its SSE wire;
+     * an in-process transport bridges from the local actor bus.
+     */
+    bridgeInto(bus: EventBus): void;
+    authenticatePassword(email: Email, password: string): Promise<AuthResponse>;
+    authenticateGoogle(credential: GoogleCredential): Promise<AuthResponse>;
+    refreshAccessToken(token: RefreshToken): Promise<TokenRefreshResponse>;
+    logout(): Promise<void>;
+    acceptTerms(): Promise<void>;
+    getCurrentUser(): Promise<UserResponse>;
+    generateMcpToken(): Promise<{
+        token: string;
+    }>;
+    getMediaToken(resourceId: ResourceId): Promise<{
+        token: string;
+    }>;
+    listUsers(): Promise<ListUsersResponse>;
+    getUserStats(): Promise<AdminUserStatsResponse>;
+    updateUser(id: UserDID, data: UpdateUserRequest): Promise<UpdateUserResponse>;
+    getOAuthConfig(): Promise<OAuthConfigResponse>;
+    backupKnowledgeBase(): Promise<Response>;
+    restoreKnowledgeBase(file: File, onProgress?: ProgressCallback): Promise<ProgressEvent>;
+    exportKnowledgeBase(params?: {
+        includeArchived?: boolean;
+    }): Promise<Response>;
+    importKnowledgeBase(file: File, onProgress?: ProgressCallback): Promise<ProgressEvent>;
+    healthCheck(): Promise<HealthCheckResponse>;
+    getStatus(): Promise<StatusResponse>;
+    /**
+     * Transport-level connection state. For HTTP, reflects the SSE
+     * connection's health; for in-process transports, typically `'open'`
+     * from construction onward (no connection to lose).
+     */
+    readonly state$: Observable<ConnectionState>;
+    dispose(): void;
+}
+interface PutBinaryRequest {
+    name: string;
+    file: File | Buffer;
+    format: ContentFormat | string;
+    storageUri: string;
+    entityTypes?: string[];
+    language?: string;
+    creationMethod?: CreationMethod | string;
+    sourceAnnotationId?: AnnotationId | string;
+    sourceResourceId?: ResourceId | string;
+    generationPrompt?: string;
+    generator?: Agent$1 | Agent$1[];
+    isDraft?: boolean;
+}
+interface IContentTransport {
+    putBinary(request: PutBinaryRequest, options?: {
+        auth?: AccessToken;
+    }): Promise<{
+        resourceId: ResourceId;
+    }>;
+    getBinary(resourceId: ResourceId, options?: {
+        accept?: ContentFormat | string;
+        auth?: AccessToken;
+    }): Promise<{
+        data: ArrayBuffer;
+        contentType: string;
+    }>;
+    getBinaryStream(resourceId: ResourceId, options?: {
+        accept?: ContentFormat | string;
+        auth?: AccessToken;
+    }): Promise<{
+        stream: ReadableStream<Uint8Array>;
+        contentType: string;
+    }>;
+    dispose(): void;
+}
+
+/**
+ * BRIDGED_CHANNELS
+ *
+ * The set of bus channels that any concrete transport bridges into the
+ * caller-supplied bus via `bridgeInto`. Transport-neutral: every concrete
+ * `ITransport` shares the same set; HTTP delivers them via SSE,
+ * in-process transports forward them directly from the local actor bus.
+ *
+ * Note: this is the *fan-in* set — channels for events the transport
+ * receives and pushes onto the client's bus. It is not the same as the
+ * channels the client emits (which is open-ended).
+ *
+ * Resource-scoped channels (joined/left via `subscribeToResource`) are
+ * tracked separately by transports that care about scope (HTTP).
+ */
+declare const BRIDGED_CHANNELS: readonly ["browse:resources-result", "browse:resources-failed", "browse:resource-result", "browse:resource-failed", "browse:annotations-result", "browse:annotations-failed", "browse:annotation-result", "browse:annotation-failed", "browse:annotation-history-result", "browse:annotation-history-failed", "browse:events-result", "browse:events-failed", "browse:referenced-by-result", "browse:referenced-by-failed", "browse:entity-types-result", "browse:entity-types-failed", "browse:directory-result", "browse:directory-failed", "browse:annotation-context-result", "browse:annotation-context-failed", "mark:delete-ok", "mark:delete-failed", "mark:create-ok", "mark:create-failed", "match:search-results", "match:search-failed", "gather:complete", "gather:failed", "gather:annotation-progress", "gather:annotation-finished", "gather:summary-result", "gather:summary-failed", "bind:body-updated", "bind:body-update-failed", "job:report-progress", "job:complete", "job:fail", "job:status-result", "job:status-failed", "job:created", "job:create-failed", "job:claimed", "job:claim-failed", "yield:clone-token-generated", "yield:clone-token-failed", "yield:clone-resource-result", "yield:clone-resource-failed", "yield:clone-created", "yield:clone-create-failed", "mark:entity-type-added", "beckon:focus", "beckon:sparkle", "bus:resume-gap"];
+type BridgedChannel = typeof BRIDGED_CHANNELS[number];
+
+/**
+ * Fuzzy Anchoring for W3C Web Annotation TextQuoteSelector
+ *
+ * Uses prefix/suffix context to disambiguate when the same text appears multiple times.
+ * Implements fuzzy matching as specified in the W3C Web Annotation Data Model.
+ *
+ * @see https://www.w3.org/TR/annotation-model/#text-quote-selector
+ */
+interface TextPosition {
+    start: number;
+    end: number;
+}
+type MatchQuality = 'exact' | 'normalized' | 'case-insensitive' | 'fuzzy';
+/**
+ * Normalize text for comparison - handles common document editing changes
+ *
+ * Collapses whitespace, converts curly quotes to straight quotes,
+ * and normalizes common punctuation variations.
+ */
+declare function normalizeText(text: string): string;
+/**
+ * Pre-computed content strings for batch fuzzy matching.
+ * Avoids recomputing normalizeText(content) and content.toLowerCase()
+ * for every annotation when processing many annotations against the same content.
+ */
+interface ContentCache {
+    normalizedContent: string;
+    lowerContent: string;
+}
+/**
+ * Build a ContentCache for a given content string.
+ * Call once per content, pass to findBestTextMatch/findTextWithContext for all annotations.
+ */
+declare function buildContentCache(content: string): ContentCache;
+/**
+ * Find best match for text in content using multi-strategy search
+ *
+ * Shared core logic used by both findTextWithContext and validateAndCorrectOffsets.
+ *
+ * @param content - Full text content to search within
+ * @param searchText - The text to find
+ * @param positionHint - Hint for where to search (TextPositionSelector.start)
+ * @param cache - Pre-computed normalized/lowered content (from buildContentCache)
+ * @returns Match with position and quality, or null if not found
+ */
+declare function findBestTextMatch(content: string, searchText: string, positionHint: number | undefined, cache: ContentCache): {
+    start: number;
+    end: number;
+    matchQuality: MatchQuality;
+} | null;
+/**
+ * Find text using exact match with optional prefix/suffix context
+ *
+ * When the exact text appears multiple times in the content, prefix and suffix
+ * are used to disambiguate and find the correct occurrence.
+ *
+ * If exact text is not found, uses multi-strategy fuzzy matching (normalization,
+ * case-insensitive, Levenshtein distance) to locate changed text.
+ *
+ * @param content - Full text content to search within
+ * @param exact - The exact text to find
+ * @param prefix - Optional text that should appear immediately before the match
+ * @param suffix - Optional text that should appear immediately after the match
+ * @param positionHint - Optional position hint (from TextPositionSelector) for fuzzy search
+ * @returns Position of the matched text, or null if not found
+ *
+ * @example
+ * ```typescript
+ * const content = "The cat sat. The cat ran.";
+ * // Find second "The cat" occurrence
+ * const pos = findTextWithContext(content, "The cat", "sat. ", " ran");
+ * // Returns { start: 13, end: 20 }
+ * ```
+ */
+declare function findTextWithContext(content: string, exact: string, prefix: string | undefined, suffix: string | undefined, positionHint: number | undefined, cache: ContentCache): TextPosition | null;
+/**
+ * Verify that a position correctly points to the exact text
+ * Useful for debugging and validation
+ */
+declare function verifyPosition(content: string, position: TextPosition, expectedExact: string): boolean;
+
+/**
+ * Locale information
+ * Copied from SDK for frontend use
+ */
+interface LocaleInfo {
+    code: string;
+    nativeName: string;
+    englishName: string;
+}
+declare const LOCALES: readonly LocaleInfo[];
+/**
+ * Get locale information by code
+ */
+declare function getLocaleInfo(code: string | undefined): LocaleInfo | undefined;
+/**
+ * Get the native name of a language by its locale code
+ */
+declare function getLocaleNativeName(code: string | undefined): string | undefined;
+/**
+ * Get the English name of a language by its locale code
+ */
+declare function getLocaleEnglishName(code: string | undefined): string | undefined;
+/**
+ * Format locale code for display as "Native Name (code)"
+ */
+declare function formatLocaleDisplay(code: string | undefined): string | undefined;
+/**
+ * Get all supported locale codes
+ */
+declare function getAllLocaleCodes(): readonly string[];
+
+/**
+ * SVG Utility Functions
+ *
+ * Utilities for creating, parsing, and manipulating W3C-compliant SVG selectors
+ * for image annotation.
+ */
+interface Point {
+    x: number;
+    y: number;
+}
+interface BoundingBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Create W3C-compliant SVG rectangle selector
+ */
+declare function createRectangleSvg(start: Point, end: Point): string;
+/**
+ * Create W3C-compliant SVG polygon selector
+ */
+declare function createPolygonSvg(points: Point[]): string;
+/**
+ * Create W3C-compliant SVG circle selector
+ */
+declare function createCircleSvg(center: Point, radius: number): string;
+/**
+ * Parse SVG selector to extract shape type and data
+ */
+declare function parseSvgSelector(svg: string): {
+    type: 'rect' | 'polygon' | 'circle' | 'path';
+    data: any;
+} | null;
+/**
+ * Normalize coordinates from display space to image native resolution
+ */
+declare function normalizeCoordinates(point: Point, displayWidth: number, displayHeight: number, imageWidth: number, imageHeight: number): Point;
+/**
+ * Scale entire SVG selector from display space to image native resolution
+ */
+declare function scaleSvgToNative(svg: string, displayWidth: number, displayHeight: number, imageWidth: number, imageHeight: number): string;
+
+/**
+ * Text context extraction utilities for W3C Web Annotation TextQuoteSelector
+ *
+ * Provides robust prefix/suffix context extraction with word boundary detection
+ * to ensure fuzzy anchoring works correctly when the same text appears multiple times.
+ *
+ * Also provides AI offset validation and correction for handling AI-generated annotations
+ * where the model may return slightly incorrect character offsets.
+ *
+ * @see https://www.w3.org/TR/annotation-model/#text-quote-selector
+ */
+
+/**
+ * Extract prefix and suffix context for TextQuoteSelector
+ *
+ * Extracts up to 64 characters before and after the selected text,
+ * extending to word boundaries to avoid cutting words in half.
+ * This ensures prefix/suffix are meaningful context for fuzzy anchoring.
+ *
+ * @param content - Full text content
+ * @param start - Start offset of selection
+ * @param end - End offset of selection
+ * @returns Object with prefix and suffix (undefined if at boundaries)
+ *
+ * @example
+ * ```typescript
+ * const content = "The United States Congress...";
+ * const context = extractContext(content, 4, 17); // "United States"
+ * // Returns: { prefix: "The ", suffix: " Congress..." }
+ * // NOT: { prefix: "nited ", suffix: "gress..." }
+ * ```
+ */
+declare function extractContext(content: string, start: number, end: number): {
+    prefix?: string;
+    suffix?: string;
+};
+/**
+ * Result of validating and correcting AI-provided annotation offsets
+ */
+interface ValidatedAnnotation {
+    start: number;
+    end: number;
+    exact: string;
+    prefix?: string;
+    suffix?: string;
+    corrected: boolean;
+    fuzzyMatched?: boolean;
+    matchQuality?: MatchQuality;
+}
+/**
+ * Validate and correct AI-provided annotation offsets with fuzzy matching tolerance
+ *
+ * AI models sometimes return offsets that don't match the actual text position,
+ * or provide text with minor variations (case differences, whitespace, typos).
+ *
+ * This function uses a multi-strategy approach:
+ * 1. Check if AI's offsets are exactly correct
+ * 2. Try exact case-sensitive search
+ * 3. Try case-insensitive search
+ * 4. Try fuzzy matching with Levenshtein distance (5% tolerance)
+ *
+ * This ensures we're maximally tolerant of AI errors while still maintaining
+ * annotation quality and logging what corrections were made.
+ *
+ * @param content - Full text content
+ * @param aiStart - Start offset from AI
+ * @param aiEnd - End offset from AI
+ * @param exact - The exact text that should be at this position (from AI)
+ * @returns Validated annotation with corrected offsets and context
+ * @throws Error if no acceptable match can be found
+ *
+ * @example
+ * ```typescript
+ * // AI said start=1143, but actual text is at 1161
+ * const result = validateAndCorrectOffsets(
+ *   content,
+ *   1143,
+ *   1289,
+ *   "the question \"whether..."
+ * );
+ * // Returns: { start: 1161, end: 1303, exact: "...", corrected: true, matchQuality: 'exact', ... }
+ * ```
+ */
+declare function validateAndCorrectOffsets(content: string, aiStart: number, aiEnd: number, exact: string): ValidatedAnnotation;
+
+/**
+ * Text encoding utilities for consistent charset handling
+ *
+ * Ensures frontend decoding matches backend decoding by respecting
+ * charset parameters in mediaType (e.g., "text/plain; charset=iso-8859-1")
+ */
+/**
+ * Extract charset from mediaType parameter
+ *
+ * @param mediaType - Media type with optional charset (e.g., "text/plain; charset=utf-8")
+ * @returns Charset name in lowercase (defaults to "utf-8")
+ *
+ * @example
+ * extractCharset("text/plain; charset=iso-8859-1") // "iso-8859-1"
+ * extractCharset("text/plain") // "utf-8"
+ */
+declare function extractCharset(mediaType: string): string;
+/**
+ * Decode ArrayBuffer to string using charset from mediaType
+ *
+ * Uses TextDecoder with the charset extracted from mediaType parameter.
+ * This ensures the same character space is used for both annotation creation
+ * (backend) and rendering (frontend).
+ *
+ * @param buffer - Binary data to decode
+ * @param mediaType - Media type with optional charset parameter
+ * @returns Decoded string in the original character space
+ *
+ * @example
+ * const buffer = new Uint8Array([...]);
+ * const text = decodeWithCharset(buffer, "text/plain; charset=iso-8859-1");
+ */
+declare function decodeWithCharset(buffer: ArrayBuffer, mediaType: string): string;
+
+/**
+ * Generic validation utilities for @semiont/api-client
+ *
+ * Pure TypeScript validation with no external dependencies.
+ * Safe to use in any JavaScript environment (Node.js, browser, Deno, etc.)
+ */
+/**
+ * Validation result types
+ */
+type ValidationSuccess<T> = {
+    success: true;
+    data: T;
+};
+type ValidationFailure = {
+    success: false;
+    error: string;
+    details?: string[];
+};
+type ValidationResult<T> = ValidationSuccess<T> | ValidationFailure;
+/**
+ * JWT Token validation
+ *
+ * Validates JWT token format (header.payload.signature).
+ * Does not verify signature - use for format validation only.
+ */
+declare const JWTTokenSchema: {
+    parse(token: unknown): string;
+    safeParse(token: unknown): ValidationResult<string>;
+};
+/**
+ * Generic validation helper with error formatting
+ *
+ * Wraps any schema's parse method with try/catch and returns ValidationResult.
+ *
+ * @example
+ * ```typescript
+ * const result = validateData(JWTTokenSchema, 'eyJ...');
+ * if (result.success) {
+ *   console.log('Valid token:', result.data);
+ * } else {
+ *   console.error('Invalid:', result.error);
+ * }
+ * ```
+ */
+declare function validateData<T>(schema: {
+    parse(data: unknown): T;
+}, data: unknown): ValidationResult<T>;
+/**
+ * Email validation helper
+ *
+ * Validates email format using RFC 5322 simplified regex.
+ *
+ * @param email - Email address to validate
+ * @returns true if valid email format
+ */
+declare function isValidEmail(email: string): boolean;
+
+/**
+ * MIME type utilities for Semiont
+ *
+ * Initial support for:
+ * - text/plain
+ * - text/markdown
+ * - image/png
+ * - image/jpeg
+ * - application/pdf
+ */
+/**
+ * Map MIME type to file extension
+ */
+declare function getExtensionForMimeType(mimeType: string): string;
+/**
+ * Detect if MIME type is an image (png or jpeg only for now)
+ */
+declare function isImageMimeType(mimeType: string): boolean;
+/**
+ * Detect if MIME type is text-based (plain or markdown only for now)
+ */
+declare function isTextMimeType(mimeType: string): boolean;
+/**
+ * Detect if MIME type is PDF
+ */
+declare function isPdfMimeType(mimeType: string): boolean;
+/**
+ * Get category for MIME type (for routing to appropriate viewer)
+ *
+ * Categories represent annotation models, not file formats:
+ * - 'text': Text-based annotations (TextPositionSelector, TextQuoteSelector)
+ * - 'image': Spatial coordinate annotations (SvgSelector, FragmentSelector)
+ *
+ * PDFs use spatial coordinates for annotations, so they belong to 'image' category.
+ */
+type MimeCategory = 'text' | 'image' | 'unsupported';
+declare function getMimeCategory(mimeType: string): MimeCategory;
 
 /**
  * Resource input/output types
@@ -4721,20 +5589,6 @@ interface ResourceFilter {
     offset?: number;
 }
 
-/**
- * Annotation types
- */
-
-type Annotation = components['schemas']['Annotation'];
-type AnnotationCategory = 'highlight' | 'reference';
-interface CreateAnnotationInternal {
-    id: string;
-    motivation: Annotation['motivation'];
-    target: Annotation['target'];
-    body?: Annotation['body'];
-    creator: components['schemas']['Agent'];
-}
-
 /**
  * Auth types
  */
@@ -5031,4 +5885,4 @@ declare function getAllPlatformTypes(): PlatformType[];
 declare const CORE_TYPES_VERSION = "0.1.0";
 declare const SDK_VERSION = "0.1.0";
 
-export { APIError, type AccessToken, type AnnotationCategory, type AnnotationId, type AnnotationUri, type AssembledAnnotation, type AuthCode, type BaseUrl, type BodyItem, type BodyItemIdentity, type BodyOperation, type Brand, type BurstBufferOptions, CHANNEL_SCHEMAS, CORE_TYPES_VERSION, CREATION_METHODS, type CloneToken, ConfigurationError, ConflictError, type ContentFormat, type CreateAnnotationInternal, type CreationMethod, type Email, type EmittableChannel, type EntityType, type EntityTypeStats, type Environment, EnvironmentConfig, type EventBase, EventBus, type EventInput, type EventMap, type EventMetadata, type EventName, type EventOfType, type EventQuery, type EventSignature, type GatheredContext, type GoogleAuthRequest, type GoogleCredential, type GraphConnection, type GraphPath, type JobId, type Logger, type MCPToken, type Motivation, NotFoundError, PERSISTED_EVENT_TYPES, type PersistedEvent, type PersistedEventType, type PlatformType, RESOURCE_BROADCAST_TYPES, type RefreshToken, type ResourceAnnotationUri, type ResourceAnnotations, type ResourceBroadcastType, type ResourceFilter, type ResourceId, type ResourceUri, SDK_VERSION, ScopedEventBus, ScriptError, type SearchQuery, type SelectionData, type Selector, SemiontError, type StoredEvent, type StoredEventLike, type ActorInferenceConfig as TomlActorInferenceConfig, type TomlFileReader, type InferenceConfig as TomlInferenceConfig, type WorkerInferenceConfig as TomlWorkerInferenceConfig, UnauthorizedError, type UpdateResourceInput, type UserDID, type UserId, ValidationError, accessToken, annotationId, annotationUri, applyBodyOperations, assembleAnnotation, authCode, baseUrl, burstBuffer, cloneToken, type components, createTomlConfigLoader, didToAgent, email, entityType, errField, findBodyItem, generateUuid, getAllPlatformTypes, getAnnotationUriFromEvent, getFragmentSelector, getSvgSelector, getTextPositionSelector, googleCredential, isAnnotationId, isArray, isBoolean, isDefined, isEventRelatedToAnnotation, isFunction, isNull, isNullish, isNumber, isObject, isResourceId, isStoredEvent, isString, isUndefined, isValidPlatformType, jobId, loadTomlConfig, mcpToken, type operations, parseEnvironment, type paths, refreshToken, resourceAnnotationUri, resourceId, resourceUri, searchQuery, serializePerKey, userDID, userId, userToAgent, userToDid, validateEnvironment, validateSvgMarkup };
+export { APIError, type AccessToken, type Annotation, type AnnotationCategory, type AnnotationId, type AnnotationUri, type AssembledAnnotation, type AuthCode, BRIDGED_CHANNELS, type BaseUrl, type BodyItem, type BodyItemIdentity, type BodyOperation, type BoundingBox, type Brand, type BridgedChannel, type BurstBufferOptions, type BusOp, CHANNEL_SCHEMAS, CORE_TYPES_VERSION, CREATION_METHODS, type CloneToken, ConfigurationError, ConflictError, type ConnectionState, type ContentCache, type ContentFormat, type CreateAnnotationInternal, type CreationMethod, type Email, type EmittableChannel, type EntityType, type EntityTypeStats, type Environment, EnvironmentConfig, type EventBase, EventBus, type EventInput, type EventMap, type EventMetadata, type EventName, type EventOfType, type EventQuery, type EventSignature, type FragmentSelector, type GatheredContext, type GoogleAuthRequest, type GoogleCredential, type GraphConnection, type GraphPath, type HealthCheckResponse, type IContentTransport, type ITransport, JWTTokenSchema, type JobId, LOCALES, type ListUsersResponse, type LocaleInfo, type Logger, type MCPToken, type MatchQuality, type MimeCategory, type Motivation, NotFoundError, PERSISTED_EVENT_TYPES, type PersistedEvent, type PersistedEventType, type PlatformType, type Point, type ProgressCallback, type ProgressEvent, type PutBinaryRequest, RESOURCE_BROADCAST_TYPES, type RefreshToken, type ResourceAnnotationUri, type ResourceAnnotations, type ResourceBroadcastType, type ResourceDescriptor, type ResourceFilter, type ResourceId, type ResourceUri, SDK_VERSION, ScopedEventBus, ScriptError, type SearchQuery, type SelectionData, type Selector, SemiontError, type StatusResponse, type StoredEvent, type StoredEventLike, type SvgSelector, type TextPosition, type TextPositionSelector, type TextQuoteSelector, type ActorInferenceConfig as TomlActorInferenceConfig, type TomlFileReader, type InferenceConfig as TomlInferenceConfig, type WorkerInferenceConfig as TomlWorkerInferenceConfig, UnauthorizedError, type UpdateResourceInput, type UpdateUserRequest, type UpdateUserResponse, type UserDID, type UserId, type UserResponse, type ValidatedAnnotation, ValidationError, type ValidationFailure, type ValidationResult, type ValidationSuccess, accessToken, annotationId, annotationUri, applyBodyOperations, assembleAnnotation, authCode, baseUrl, buildContentCache, burstBuffer, busLog, busLogEnabled, cloneToken, type components, createCircleSvg, createPolygonSvg, createRectangleSvg, createTomlConfigLoader, decodeRepresentation, decodeWithCharset, didToAgent, email, entityType, errField, extractBoundingBox, extractCharset, extractContext, findBestTextMatch, findBodyItem, findTextWithContext, formatLocaleDisplay, generateUuid, getAllLocaleCodes, getAllPlatformTypes, getAnnotationExactText, getAnnotationUriFromEvent, getBodySource, getBodyType, getChecksum, getCommentText, getCreator, getDerivedFrom, getExactText, getExtensionForMimeType, getFragmentSelector, getLanguage, getLocaleEnglishName, getLocaleInfo, getLocaleNativeName, getMimeCategory, getNodeEncoding, getPrimaryMediaType, getPrimaryRepresentation, getPrimarySelector, getResourceEntityTypes, getResourceId, getStorageUri, getSvgSelector, getTargetSelector, getTargetSource, getTextPositionSelector, getTextQuoteSelector, googleCredential, hasTargetSelector, isAnnotationId, isArchived, isArray, isAssessment, isBodyResolved, isBoolean, isComment, isDefined, isDraft, isEventRelatedToAnnotation, isFunction, isHighlight, isImageMimeType, isNull, isNullish, isNumber, isObject, isPdfMimeType, isReference, isResolvedReference, isResourceId, isStoredEvent, isString, isStubReference, isTag, isTextMimeType, isUndefined, isValidEmail, isValidPlatformType, jobId, loadTomlConfig, mcpToken, normalizeCoordinates, normalizeText, type operations, parseEnvironment, parseSvgSelector, type paths, refreshToken, resourceAnnotationUri, resourceId, resourceUri, scaleSvgToNative, searchQuery, serializePerKey, setBusLogTraceIdProvider, userDID, userId, userToAgent, userToDid, validateAndCorrectOffsets, validateData, validateEnvironment, validateSvgMarkup, verifyPosition };